OpenAPI Auto-Generated http-client Bindings to httpstan
The library in lib provides auto-generated-from-OpenAPI http-client bindings to the httpstan API.
OpenApi Version: 3.0.1
Installation
Installation follows the standard approach to installing Stack-based projects.
- Install the Haskell
stack tool.
- To build the package, and generate the documentation (recommended):
stack haddock
which will generate docs for this lib in the docs folder.
To generate the docs in the normal location (to enable hyperlinks to external libs), remove
build:
haddock-arguments:
haddock-args:
- "--odir=./docs"
from the stack.yaml file and run stack haddock again.
- To run unit tests:
stack test
OpenAPI-Generator
The code generator that produced this library, and which explains how
to obtain and use the openapi-generator cli tool lives at
https://openapi-generator.tech
The generator-name argument (--generator-name) passed to the cli tool used should be
haskell-http-client
Unsupported OpenAPI Features
This is beta software; other cases may not be supported.
Codegen "additional properties" parameters
These options allow some customization of the code generation process.
haskell-http-client additional properties:
| OPTION |
DESCRIPTION |
DEFAULT |
ACTUAL |
| allowFromJsonNulls |
allow JSON Null during model decoding from JSON |
true |
true |
| allowNonUniqueOperationIds |
allow different API modules to contain the same operationId. Each API must be imported qualified |
false |
false |
| allowToJsonNulls |
allow emitting JSON Null during model encoding to JSON |
false |
false |
| baseModule |
Set the base module namespace |
|
Httpstan |
| cabalPackage |
Set the cabal package name, which consists of one or more alphanumeric words separated by hyphens |
|
httpstan |
| 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 |
| customTestInstanceModule |
test module used to provide typeclass instances for types not known by the generator |
|
|
| configType |
Set the name of the type used for configuration |
|
HttpstanConfig |
| dateFormat |
format string used to parse/render a date |
%Y-%m-%d |
%Y-%m-%d |
| dateTimeFormat |
format string used to parse/render a datetime. (Defaults to formatISO8601Millis when not provided) |
|
|
| dateTimeParseFormat |
overrides the format string used to parse a datetime |
|
|
| generateEnums |
Generate specific datatypes for OpenAPI enums |
true |
true |
| generateFormUrlEncodedInstances |
Generate FromForm/ToForm instances for models used by x-www-form-urlencoded operations (model fields must be primitive types) |
true |
true |
| generateLenses |
Generate Lens optics for Models |
true |
true |
| generateModelConstructors |
Generate smart constructors (only supply required fields) for models |
true |
true |
| inlineMimeTypes |
Inline (hardcode) the content-type and accept parameters on operations, when there is only 1 option |
true |
true |
| modelDeriving |
Additional classes to include in the deriving() clause of Models |
|
|
| requestType |
Set the name of the type used to generate requests |
|
HttpstanRequest |
| strictFields |
Add strictness annotations to all model fields |
true |
true |
| useKatip |
Sets the default value for the UseKatip cabal flag. If true, the katip package provides logging instead of monad-logger |
true |
true |
| queryExtraUnreserved |
Configures additional querystring characters which must not be URI encoded, e.g. '+' or ':' |
|
|
An example setting dateTimeFormat and strictFields:
java -jar openapi-generator-cli.jar generate -i petstore.yaml -g haskell-http-client -o output/haskell-http-client --additional-properties=dateTimeFormat="%Y-%m-%dT%H:%M:%S%Q%z" --additional-properties=strictFields=false
View the full list of Codegen "config option" parameters with the command:
java -jar openapi-generator-cli.jar config-help -g haskell-http-client
Usage Notes
Example Petstore Haddock documentation
An example of the generated haddock documentation targeting the server http://petstore.swagger.io/ (Petstore) can be found here
Example Petstore App
An example application using the auto-generated haskell-http-client bindings for the server http://petstore.swagger.io/ can be found here
This library is intended to be imported qualified.
Modules
| MODULE |
NOTES |
| Httpstan.Client |
use the "dispatch" functions to send requests |
| Httpstan.Core |
core functions, config and request types |
| Httpstan.API |
construct api requests |
| Httpstan.Model |
describes api models |
| Httpstan.MimeTypes |
encoding/decoding MIME types (content-types/accept) |
| Httpstan.ModelLens |
lenses for model fields |
| Httpstan.Logging |
logging functions and utils |
MimeTypes
This library adds type safety around what OpenAPI specifies as
Produces and Consumes for each Operation (e.g. the list of MIME types an
Operation can Produce (using 'accept' headers) and Consume (using 'content-type' headers).
For example, if there is an Operation named addFoo, there will be a
data type generated named AddFoo (note the capitalization), which
describes additional constraints and actions on the addFoo operation
via its typeclass instances. These typeclass instances can be viewed
in GHCi or via the Haddocks.
- required parameters are included as function arguments to addFoo
- optional non-body parameters are included by using
applyOptionalParam
- optional body parameters are set by using
setBodyParam
Example code generated for pretend addFoo operation:
data AddFoo
instance Consumes AddFoo MimeJSON
instance Produces AddFoo MimeJSON
instance Produces AddFoo MimeXML
instance HasBodyParam AddFoo FooModel
instance HasOptionalParam AddFoo FooName
instance HasOptionalParam AddFoo FooId
this would indicate that:
- the addFoo operation can consume JSON
- the addFoo operation produces JSON or XML, depending on the argument passed to the dispatch function
- the addFoo operation can set it's body param of FooModel via
setBodyParam
- the addFoo operation can set 2 different optional parameters via
applyOptionalParam
If the OpenAPI spec doesn't declare it can accept or produce a certain
MIME type for a given Operation, you should either add a Produces or
Consumes instance for the desired MIME types (assuming the server
supports it), use dispatchLbsUnsafe or modify the OpenAPI spec and
run the generator again.
New MIME type instances can be added via MimeType/MimeRender/MimeUnrender
Only JSON instances are generated by default, and in some case
x-www-form-urlencoded instances (FromFrom, ToForm) will also be
generated if the model fields are primitive types, and there are
Operations using x-www-form-urlencoded which use those models.
Authentication
A haskell data type will be generated for each OpenAPI authentication type.
If for example the AuthMethod AuthOAuthFoo is generated for OAuth operations, then
addAuthMethod should be used to add the AuthMethod config.
When a request is dispatched, if a matching auth method is found in
the config, it will be applied to the request.
Example
mgr <- newManager defaultManagerSettings
config0 <- withStdoutLogging =<< newConfig
let config = config0
`addAuthMethod` AuthOAuthFoo "secret-key"
let addFooRequest =
addFoo
(ContentType MimeJSON)
(Accept MimeXML)
(ParamBar paramBar)
(ParamQux paramQux)
modelBaz
`applyOptionalParam` FooId 1
`applyOptionalParam` FooName "name"
`setHeader` [("qux_header","xxyy")]
addFooResult <- dispatchMime mgr config addFooRequest
See the example app and the haddocks for details.