openapi-generator/samples/client/petstore/haskell-http-client

OpenAPI Auto-Generated http-client Bindings to OpenAPI Petstore

The library in lib provides auto-generated-from-OpenAPI http-client bindings to the OpenAPI Petstore API.

OpenApi Version: 3.0.0

Installation

Installation follows the standard approach to installing Stack-based projects.

1. Install the Haskell stack tool.
2. 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.

3. 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

• Model Inheritance

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		OpenAPIPetstore
cabalPackage	Set the cabal package name, which consists of one or more alphanumeric words separated by hyphens		openapi-petstore
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
configType	Set the name of the type used for configuration		OpenAPIPetstoreConfig
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)
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		OpenAPIPetstoreRequest
strictFields	Add strictness annotations to all model fields	true	true
useMonadLogger	Use the monad-logger package to provide logging (if instead false, use the katip logging package)	false	false

An example setting strictFields and dateTimeFormat:

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"

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
OpenAPIPetstore.Client	use the "dispatch" functions to send requests
OpenAPIPetstore.Core	core funcions, config and request types
OpenAPIPetstore.API	construct api requests
OpenAPIPetstore.Model	describes api models
OpenAPIPetstore.MimeTypes	encoding/decoding MIME types (content-types/accept)
OpenAPIPetstore.ModelLens	lenses for model fields
OpenAPIPetstore.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.