github.com/kaisawind/go-swagger@v0.19.0/docs/generate/client.md (about) 1 # Generate an API client from a swagger spec 2 3 The toolkit has a command that will let you generate a client. 4 5 ### Client usage 6 7 ``` 8 Usage: 9 swagger [OPTIONS] generate client [client-OPTIONS] 10 11 generate all the files for a client library 12 13 Application Options: 14 -q, --quiet silence logs 15 -o, --output=LOG-FILE redirect logs to file 16 17 Help Options: 18 -h, --help Show this help message 19 20 [client command options] 21 -f, --spec= the spec file to use (default swagger.{json,yml,yaml}) 22 -a, --api-package= the package to save the operations (default: operations) 23 -m, --model-package= the package to save the models (default: models) 24 -s, --server-package= the package to save the server specific code (default: restapi) 25 -c, --client-package= the package to save the client specific code (default: client) 26 -t, --target= the base directory for generating the files (default: ./) 27 -T, --template-dir= alternative template override directory 28 -C, --config-file= configuration file to use for overriding template options 29 -r, --copyright-file= copyright file used to add copyright header 30 --existing-models= use pre-generated models e.g. github.com/foobar/model 31 --additional-initialism= consecutive capitals that should be considered intialisms 32 --with-expand expands all $ref's in spec prior to generation (shorthand to --with-flatten=expand) 33 --with-flatten=[minimal|full|expand|verbose|noverbose|remove-unused] flattens all $ref's in spec prior to generation (default: minimal, verbose) 34 -A, --name= the name of the application, defaults to a mangled value of info.title 35 -O, --operation= specify an operation to include, repeat for multiple 36 --tags= the tags to include, if not specified defaults to all 37 -P, --principal= the model to use for the security principal 38 -M, --model= specify a model to include, repeat for multiple 39 --default-scheme= the default scheme for this client (default: http) 40 --default-produces= the default mime type that API operations produce (default: application/json) 41 --skip-models no models will be generated when this flag is specified 42 --skip-operations no operations will be generated when this flag is specified 43 --dump-data when present dumps the json for the template generator instead of generating files 44 --skip-validation skips validation of spec prior to generation 45 ``` 46 47 ### Build a client 48 49 There is an example client provided at: https://github.com/go-swagger/go-swagger/tree/master/examples/todo-list/client 50 51 To generate a client: 52 53 ``` 54 swagger generate client -f [http-url|filepath] -A [application-name] [--principal [principal-name]] 55 ``` 56 57 If you want to debug what the client is sending and receiving you can set the environment value DEBUG to a non-empty 58 value. 59 60 61 Use a default client, which has an HTTP transport: 62 63 ```go 64 import ( 65 "log" 66 67 "github.com/myproject/client/operations" 68 "github.com/go-openapi/strfmt" 69 "github.com/go-openapi/spec" 70 71 apiclient "github.com/myproject/client" 72 httptransport "github.com/go-openapi/runtime/client" 73 ) 74 75 func main() { 76 77 // make the request to get all items 78 resp, err := apiclient.Default.Operations.All(operations.AllParams{}) 79 if err != nil { 80 log.Fatal(err) 81 } 82 fmt.Printf("%#v\n", resp.Payload) 83 } 84 ``` 85 86 The client runtime allows for a number of [configuration 87 options](https://godoc.org/github.com/go-openapi/runtime/client#Runtime) to be set. 88 To then use the client, and override the host, with a HTTP transport: 89 90 ```go 91 import ( 92 "os" 93 "log" 94 95 "github.com/myproject/client/operations" 96 "github.com/go-openapi/strfmt" 97 "github.com/go-openapi/spec" 98 99 apiclient "github.com/myproject/client" 100 httptransport "github.com/go-openapi/runtime/client" 101 ) 102 103 func main() { 104 105 // create the transport 106 transport := httptransport.New(os.Getenv("TODOLIST_HOST"), "", nil) 107 108 // create the API client, with the transport 109 client := apiclient.New(transport, strfmt.Default) 110 111 // to override the host for the default client 112 // apiclient.Default.SetTransport(transport) 113 114 // make the request to get all items 115 resp, err := client.Operations.All(operations.AllParams{}) 116 if err != nil { 117 log.Fatal(err) 118 } 119 fmt.Printf("%#v\n", resp.Payload) 120 } 121 ``` 122 123 ### Authentication 124 125 The client supports 3 authentication schemes: 126 127 * [Basic Auth](https://godoc.org/github.com/go-openapi/runtime/client#BasicAuth) 128 * [API key auth in header or query](https://godoc.org/github.com/go-openapi/runtime/client#APIKeyAuth) 129 * [Bearer token header for oauth2](https://godoc.org/github.com/go-openapi/runtime/client#BearerToken) 130 131 ```go 132 import ( 133 "os" 134 "log" 135 136 "github.com/myproject/client/operations" 137 "github.com/go-openapi/strfmt" 138 "github.com/go-openapi/spec" 139 140 apiclient "github.com/myproject/client" 141 httptransport "github.com/go-openapi/runtime/client" 142 ) 143 144 func main() { 145 146 // create the API client 147 client := apiclient.New(httptransport.New("", "", nil), strfmt.Default) 148 149 // make the authenticated request to get all items 150 bearerTokenAuth := httptransport.BearerToken(os.Getenv("API_ACCESS_TOKEN")) 151 // basicAuth := httptransport.BasicAuth(os.Getenv("API_USER"), os.Getenv("API_PASSWORD")) 152 // apiKeyQueryAuth := httptransport.APIKeyAuth("apiKey", "query", os.Getenv("API_KEY")) 153 // apiKeyHeaderAuth := httptransport.APIKeyAuth("X-API-TOKEN", "header", os.Getenv("API_KEY")) 154 resp, err := client.Operations.All(operations.AllParams{}, bearerTokenAuth) 155 // resp, err := client.Operations.All(operations.AllParams{}, basicAuth) 156 // resp, err := client.Operations.All(operations.AllParams{}, apiKeyQueryAuth) 157 // resp, err := client.Operations.All(operations.AllParams{}, apiKeyHeaderAuth) 158 if err != nil { 159 log.Fatal(err) 160 } 161 fmt.Printf("%#v\n", resp.Payload) 162 } 163 ```