|
1 | | -## Swagger Auto-Generated [http-client](https://www.stackage.org/lts-9.0/package/http-client-0.5.7.0) Bindings to `Kubernetes` |
| 1 | +## OpenAPI Auto-Generated [http-client](https://www.stackage.org/lts-10.0/package/http-client-0.5.7.1) Bindings to `Kubernetes` |
2 | 2 |
|
3 | | -The library in `lib` provides auto-generated-from-Swagger [http-client](https://www.stackage.org/lts-9.0/package/http-client-0.5.7.0) bindings to the Kubernetes API. |
| 3 | +The library in `lib` provides auto-generated-from-OpenAPI [http-client](https://www.stackage.org/lts-10.0/package/http-client-0.5.7.1) bindings to the Kubernetes API. |
4 | 4 |
|
5 | | -Targeted swagger version: 2.0 |
| 5 | +OpenApi Version: 3.0.1 |
6 | 6 |
|
7 | | -OpenAPI-Specification: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md |
| 7 | +## Installation |
8 | 8 |
|
9 | | -## Usage |
| 9 | +Installation follows the standard approach to installing Stack-based projects. |
10 | 10 |
|
11 | | -Please refer to the README of the `kubernetes-client-helper` package. |
| 11 | +1. Install the [Haskell `stack` tool](http://docs.haskellstack.org/en/stable/README). |
| 12 | +2. To build the package, and generate the documentation (recommended): |
| 13 | +``` |
| 14 | +stack haddock |
| 15 | +``` |
| 16 | +which will generate docs for this lib in the `docs` folder. |
| 17 | + |
| 18 | +To generate the docs in the normal location (to enable hyperlinks to external libs), remove |
| 19 | +``` |
| 20 | +build: |
| 21 | + haddock-arguments: |
| 22 | + haddock-args: |
| 23 | + - "--odir=./docs" |
| 24 | +``` |
| 25 | +from the stack.yaml file and run `stack haddock` again. |
| 26 | + |
| 27 | +3. To run unit tests: |
| 28 | +``` |
| 29 | +stack test |
| 30 | +``` |
| 31 | + |
| 32 | +## OpenAPI-Generator |
| 33 | + |
| 34 | +The code generator that produced this library, and which explains how |
| 35 | +to obtain and use the openapi-generator cli tool lives at |
| 36 | + |
| 37 | +https://openapi-generator.tech |
| 38 | + |
| 39 | +The _generator-name_ argument (`--generator-name`) passed to the cli tool used should be |
| 40 | + |
| 41 | +``` |
| 42 | +haskell-http-client |
| 43 | +``` |
| 44 | + |
| 45 | +### Unsupported OpenAPI Features |
| 46 | + |
| 47 | +* Model Inheritance |
| 48 | + |
| 49 | +This is beta software; other cases may not be supported. |
| 50 | + |
| 51 | +### Codegen "additional properties" parameters |
| 52 | + |
| 53 | +These options allow some customization of the code generation process. |
| 54 | + |
| 55 | +**haskell-http-client additional properties:** |
| 56 | + |
| 57 | +| OPTION | DESCRIPTION | DEFAULT | ACTUAL | |
| 58 | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------- | |
| 59 | +| allowFromJsonNulls | allow JSON Null during model decoding from JSON | true | true | |
| 60 | +| allowNonUniqueOperationIds | allow *different* API modules to contain the same operationId. Each API must be imported qualified | false | true | |
| 61 | +| allowToJsonNulls | allow emitting JSON Null during model encoding to JSON | false | false | |
| 62 | +| baseModule | Set the base module namespace | | Kubernetes.OpenAPI | |
| 63 | +| cabalPackage | Set the cabal package name, which consists of one or more alphanumeric words separated by hyphens | | kubernetes-openapi-client-gen | |
| 64 | +| cabalVersion | Set the cabal version number, consisting of a sequence of one or more integers separated by dots | 0.1.0.0 | 0.1.0.0 | |
| 65 | +| configType | Set the name of the type used for configuration | | KubernetesClientConfig | |
| 66 | +| dateFormat | format string used to parse/render a date | %Y-%m-%d | %Y-%m-%d | |
| 67 | +| dateTimeFormat | format string used to parse/render a datetime. (Defaults to [formatISO8601Millis][1] when not provided) | | | |
| 68 | +| generateEnums | Generate specific datatypes for OpenAPI enums | true | true | |
| 69 | +| generateFormUrlEncodedInstances | Generate FromForm/ToForm instances for models used by x-www-form-urlencoded operations (model fields must be primitive types) | true | true | |
| 70 | +| generateLenses | Generate Lens optics for Models | true | true | |
| 71 | +| generateModelConstructors | Generate smart constructors (only supply required fields) for models | true | true | |
| 72 | +| inlineMimeTypes | Inline (hardcode) the content-type and accept parameters on operations, when there is only 1 option | true | true | |
| 73 | +| modelDeriving | Additional classes to include in the deriving() clause of Models | | | |
| 74 | +| requestType | Set the name of the type used to generate requests | | KubernetesRequest | |
| 75 | +| strictFields | Add strictness annotations to all model fields | true | true | |
| 76 | +| useKatip | Sets the default value for the UseKatip cabal flag. If true, the katip package provides logging instead of monad-logger | true | true | |
| 77 | + |
| 78 | +[1]: https://www.stackage.org/haddock/lts-9.0/iso8601-time-0.1.4/Data-Time-ISO8601.html#v:formatISO8601Millis |
| 79 | + |
| 80 | +An example setting _strictFields_ and _dateTimeFormat_: |
| 81 | + |
| 82 | +``` |
| 83 | +java -jar openapi-generator-cli.jar generate -i petstore.yaml -g haskell-http-client -o output/haskell-http-client -DstrictFields=true -DdateTimeFormat="%Y-%m-%dT%H:%M:%S%Q%z" |
| 84 | +``` |
| 85 | + |
| 86 | +View the full list of Codegen "config option" parameters with the command: |
| 87 | + |
| 88 | +``` |
| 89 | +java -jar openapi-generator-cli.jar config-help -g haskell-http-client |
| 90 | +``` |
| 91 | + |
| 92 | +## Usage Notes |
| 93 | + |
| 94 | +### Example Petstore Haddock documentation |
| 95 | + |
| 96 | +An example of the generated haddock documentation targeting the server http://petstore.swagger.io/ (Petstore) can be found [here][2] |
| 97 | + |
| 98 | +[2]: https://hackage.haskell.org/package/swagger-petstore |
| 99 | + |
| 100 | +### Example Petstore App |
| 101 | + |
| 102 | +An example application using the auto-generated haskell-http-client bindings for the server http://petstore.swagger.io/ can be found [here][3] |
| 103 | + |
| 104 | +[3]: https://github.com/openapitools/openapi-generator/tree/master/samples/client/petstore/haskell-http-client/example-app |
| 105 | + |
| 106 | +This library is intended to be imported qualified. |
| 107 | + |
| 108 | +### Modules |
| 109 | + |
| 110 | +| MODULE | NOTES | |
| 111 | +| ------------------- | --------------------------------------------------- | |
| 112 | +| Kubernetes.OpenAPI.Client | use the "dispatch" functions to send requests | |
| 113 | +| Kubernetes.OpenAPI.Core | core funcions, config and request types | |
| 114 | +| Kubernetes.OpenAPI.API | construct api requests | |
| 115 | +| Kubernetes.OpenAPI.Model | describes api models | |
| 116 | +| Kubernetes.OpenAPI.MimeTypes | encoding/decoding MIME types (content-types/accept) | |
| 117 | +| Kubernetes.OpenAPI.ModelLens | lenses for model fields | |
| 118 | +| Kubernetes.OpenAPI.Logging | logging functions and utils | |
| 119 | + |
| 120 | + |
| 121 | +### MimeTypes |
| 122 | + |
| 123 | +This library adds type safety around what OpenAPI specifies as |
| 124 | +Produces and Consumes for each Operation (e.g. the list of MIME types an |
| 125 | +Operation can Produce (using 'accept' headers) and Consume (using 'content-type' headers). |
| 126 | + |
| 127 | +For example, if there is an Operation named _addFoo_, there will be a |
| 128 | +data type generated named _AddFoo_ (note the capitalization), which |
| 129 | +describes additional constraints and actions on the _addFoo_ operation |
| 130 | +via its typeclass instances. These typeclass instances can be viewed |
| 131 | +in GHCi or via the Haddocks. |
| 132 | + |
| 133 | +* required parameters are included as function arguments to _addFoo_ |
| 134 | +* optional non-body parameters are included by using `applyOptionalParam` |
| 135 | +* optional body parameters are set by using `setBodyParam` |
| 136 | + |
| 137 | +Example code generated for pretend _addFoo_ operation: |
| 138 | + |
| 139 | +```haskell |
| 140 | +data AddFoo |
| 141 | +instance Consumes AddFoo MimeJSON |
| 142 | +instance Produces AddFoo MimeJSON |
| 143 | +instance Produces AddFoo MimeXML |
| 144 | +instance HasBodyParam AddFoo FooModel |
| 145 | +instance HasOptionalParam AddFoo FooName |
| 146 | +instance HasOptionalParam AddFoo FooId |
| 147 | +``` |
| 148 | + |
| 149 | +this would indicate that: |
| 150 | + |
| 151 | +* the _addFoo_ operation can consume JSON |
| 152 | +* the _addFoo_ operation produces JSON or XML, depending on the argument passed to the dispatch function |
| 153 | +* the _addFoo_ operation can set it's body param of _FooModel_ via `setBodyParam` |
| 154 | +* the _addFoo_ operation can set 2 different optional parameters via `applyOptionalParam` |
| 155 | + |
| 156 | +If the OpenAPI spec doesn't declare it can accept or produce a certain |
| 157 | +MIME type for a given Operation, you should either add a Produces or |
| 158 | +Consumes instance for the desired MIME types (assuming the server |
| 159 | +supports it), use `dispatchLbsUnsafe` or modify the OpenAPI spec and |
| 160 | +run the generator again. |
| 161 | + |
| 162 | +New MIME type instances can be added via MimeType/MimeRender/MimeUnrender |
| 163 | + |
| 164 | +Only JSON instances are generated by default, and in some case |
| 165 | +x-www-form-urlencoded instances (FromFrom, ToForm) will also be |
| 166 | +generated if the model fields are primitive types, and there are |
| 167 | +Operations using x-www-form-urlencoded which use those models. |
| 168 | + |
| 169 | +### Authentication |
| 170 | + |
| 171 | +A haskell data type will be generated for each OpenAPI authentication type. |
| 172 | + |
| 173 | +If for example the AuthMethod `AuthOAuthFoo` is generated for OAuth operations, then |
| 174 | +`addAuthMethod` should be used to add the AuthMethod config. |
| 175 | + |
| 176 | +When a request is dispatched, if a matching auth method is found in |
| 177 | +the config, it will be applied to the request. |
| 178 | + |
| 179 | +### Example |
| 180 | + |
| 181 | +```haskell |
| 182 | +mgr <- newManager defaultManagerSettings |
| 183 | +config0 <- withStdoutLogging =<< newConfig |
| 184 | +let config = config0 |
| 185 | + `addAuthMethod` AuthOAuthFoo "secret-key" |
| 186 | + |
| 187 | +let addFooRequest = |
| 188 | + addFoo |
| 189 | + (ContentType MimeJSON) |
| 190 | + (Accept MimeXML) |
| 191 | + (ParamBar paramBar) |
| 192 | + (ParamQux paramQux) |
| 193 | + modelBaz |
| 194 | + `applyOptionalParam` FooId 1 |
| 195 | + `applyOptionalParam` FooName "name" |
| 196 | + `setHeader` [("qux_header","xxyy")] |
| 197 | +addFooResult <- dispatchMime mgr config addFooRequest |
| 198 | +``` |
| 199 | + |
| 200 | +See the example app and the haddocks for details. |
0 commit comments