The swagger-petstore package

[ Tags: library, mit, web ] [ Propose Tags ]

. Client library for calling the swagger-petstore API based on http-client.


base path:

Swagger Petstore API version: 1.0.0

OpenAPI spec version: 2.0


[Skip to Readme]


Dependencies aeson (>=1.0 && <2.0), base (>=4.7 && <5.0), base64-bytestring (>1.0 && <2.0), bytestring (>=0.10.0 && <0.11), case-insensitive, containers (>= && <0.6), deepseq (>=1.4 && <1.6), exceptions (>=0.4), http-api-data (>=0.3.4 && <0.4), http-client (==0.5.*), http-client-tls, http-media (>=0.4 && <0.8), http-types (>=0.8 && <0.10), iso8601-time (>=0.1.3 && <0.2.0), katip (>=0.4 && <0.6), microlens (>=0.4.3 && <0.5), mtl (>=2.2.1), network (>=2.6.2 && <2.7), random (>=1.1), safe-exceptions (<0.2), text (>=0.11 && <1.3), time (>=1.5 && <1.9), transformers (>=, unordered-containers, vector (>=0.10.9 && <0.13) [details]
License MIT
Copyright 2017 - Jon Schoning
Author Jon Schoning
Category Web
Home page
Uploaded Wed Oct 18 03:34:11 UTC 2017 by jonschoning
Distributions NixOS:
Downloads 139 total (113 in the last 30 days)
Rating 0.0 (0 ratings) [clear rating]
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-10-18 [all 1 reports]
Hackage Matrix CI




Maintainer's Corner

For package maintainers and hackage trustees

Readme for swagger-petstore-

[back to package description]

Swagger Auto-Generated http-client Bindings to SwaggerPetstore

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

Targeted swagger version: 2.0



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

    - "--odir=./docs"

from the stack.yaml file and run stack haddock again.

  1. To run unit tests:
stack test


The code generator that produced this library, and which explains how to obtain and use the swagger-codegen cli tool lives at

The language argument (--lang) passed to the cli tool used should be


Unsupported Swagger Features

  • Model Inheritance

  • Default Parameter Values

  • Enum Parameters

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 | | allowToJsonNulls | allow emitting JSON Null during model encoding to JSON | false | false | | 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) | | | | 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 | | inlineConsumesContentTypes | Inline (hardcode) the content-type on operations that do not have multiple content-types (Consumes) | false | false | | modelDeriving | Additional classes to include in the deriving() clause of Models | | | | 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 swagger-codegen-cli.jar generate -i petstore.yaml -l 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 swagger-codegen-cli.jar config-help -l haskell-http-client

Usage Notes

Example SwaggerPetstore Haddock documentation

An example of the generated haddock documentation targeting the server (SwaggerPetstore) can be found here

Example SwaggerPetstore App

An example application using the auto-generated haskell-http-client bindings for the server can be found here

This library is intended to be imported qualified.


| MODULE | NOTES | | ------------------- | --------------------------------------------------- | | SwaggerPetstore.Client | use the "dispatch" functions to send requests | | SwaggerPetstore.Core | core funcions, config and request types | | SwaggerPetstore.API | construct api requests | | SwaggerPetstore.Model | describes api models | | SwaggerPetstore.MimeTypes | encoding/decoding MIME types (content-types/accept) | | SwaggerPetstore.ModelLens | lenses for model fields | | SwaggerPetstore.Logging | logging functions and utils |


This library adds type safety around what swagger 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.

  • requried 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 swagger 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 swagger 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.


A haskell data type will be generated for each swagger 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.


mgr <- newManager defaultManagerSettings
config0 <- withStdoutLogging =<< newConfig 
let config = config0
    `addAuthMethod` AuthOAuthFoo "secret-key"

let addFooRequest = addFoo MimeJSON foomodel requiredparam1 requiredparam2
  `applyOptionalParam` FooId 1
  `applyOptionalParam` FooName "name"
  `setHeader` [("qux_header","xxyy")]
addFooResult <- dispatchMime mgr config addFooRequest MimeXML

See the example app and the haddocks for details.