servant-swagger

Generate a Swagger/OpenAPI/OAS 2.0 specification for your servant API.

https://github.com/haskell-servant/servant/tree/master/servant-swagger#readme

Version on this page:1.2@rev:4
LTS Haskell 23.4:1.2.1
Stackage Nightly 2024-12-09:1.2.1
Latest on Hackage:1.2.1

See all snapshots servant-swagger appears in

BSD-3-Clause licensed by Servant Contributors
Maintained by [email protected]
This version can be pinned in stack with:servant-swagger-1.2@sha256:db79bf9d08440843aae06780e1d139d374f29317d01276de315236f4c0256d63,4790

Module documentation for 1.2

Used by 1 package in nightly-2024-08-08(full list with versions):
servant-auth-swagger

servant-swagger

Hackage Stackage LTS Stackage Nightly

Swagger 2.0 conforming json for servant APIs.

servant-swagger robot

Motivation

Swagger is a project used to describe and document RESTful APIs. Unlike Servant it is language-agnostic and thus is quite popular among developers in different languages. It also exists for a longer time and has more tools to work with.

This package provides means to generate Swagger specification for a Servant API and also to partially test whether API conforms with its specification.

Generated Swagger specification then can be used for many things such as

Usage

Please refer to haddock documentation.

Some examples can be found in example/ directory.

Try it out

All generated swagger specifications can be interactively viewed on Swagger Editor.

Ready-to-use specification can be served as JSON and interactive API documentation can be displayed using Swagger UI.

Many Swagger tools, including server and client code generation for many languages, can be found on Swagger’s Tools and Integrations page.

Contributing

We are happy to receive bug reports, fixes, documentation enhancements, and other improvements.

Please report bugs via the github issue tracker.

Changes

1.2

  • WithResource combinator for Servant-managed resources #1630

    For servant-swagger, this meant the addition of a HasSwagger instance.

1.1.9

  • Support servant-0.18

1.1.8

  • Support servant-0.17

1.1.7.1

  • Support swagger2-2.4

1.1.7

  • Support servant-0.15
    • support for ‘Stream’ and ‘StreamBody’ combinators
    • orphan ‘ToSchema (SourceT m a)’ instance
  • Fix BodyTypes to work with generalized ReqBody’ #88

1.1.6

  • Fixes:

    • validateEveryToJSON now prints validation errors

  • Notes:

    • GHC-8.6 compatible release

1.1.5

  • Notes:
    • servant-0.13 compatible release
    • Drops compatibility with previous servant versions.

1.1.4

  • Notes:
    • servant-0.12 compatible release

1.1.3.1

  • Notes:
    • GHC-8.2 compatible release

1.1.3

  • Notes:
    • servant-0.11 compatible release

1.1.2.1

  • Notes:
    • servant-0.10 compatible release

1.1.2

  • Minor fixes:
    • Support for aeson-1, insert-ordered-containers-0.2
    • CaptureAll instance

1.1.1

  • Minor fixes:
    • Fix unused-imports and unused-foralls warnings;
    • Fix tests to match swagger2-2.1.1 (add example property for UTCTime schema).

1.1

  • Breaking changes:

    • Requires swagger2 >= 2.1
    • Requires servant >= 0.5

  • Notes:

    • GHC-8.0 compatible release

1.0.3

  • Fixes:
    • Improve compile-time performance of BodyTypes even further (see 18e0d95)!

1.0.2

  • Minor changes:

    • Add GHC 7.8 support (see #26).

  • Fixes:

    • Improve compile-time performance of BodyTypes (see #25).

1.0.1

  • Fixes:
    • Stop using Data.Swagger.Internal;
    • Documentation fixes (links to examples).

1.0

  • Major changes (see #24):

    • Switch to swagger2-2.*;
    • Add automatic ToJSON/ToSchema validation tests;
    • Add great documentation;
    • Export some type-level functions for servant API.

  • Minor changes:

    • Rework Todo API example;
    • Stop exporting ToResponseHeader, AllAccept and AllToResponseHeader (see bd50db4);
    • Change maintainer, update authors/copyrights (see 1a62681);
    • Include changelog and example files into extra-source-files.

0.1.2

  • Fixes:
    • Fix default spec for ReqBody param to be required (see #22);
    • Set version bounds for swagger2.

0.1.1

  • Fixes:
    • Fix subOperations to filter endpoints also by method (see #18);
    • Fix response schema in ToSwagger instance for Header (see b59e557).

0.1

  • Major changes
    • Use swagger2 for data model (see #9); this changes almost everything.