@hackage / servant-openapi-hs

Generate an OpenAPI 3.1 specification for your servant API.

Latest5.1.0

Changelog

5.1.0

  • Breaking: MultiVerb now documents each response alternative under its own content types. RespondAs ct keeps ct, Respond inherits the endpoint's media-type list, and RespondEmpty stays bodyless. Previously every alternative was rendered against a JSON default and then had the endpoint's content-type list reapplied wholesale, which discarded a RespondAs content type. Alternatives sharing a status code now retain every media type they declared instead of collapsing to one.
  • Breaking: Servant.OpenApi.Internal's IsSwaggerResponse and IsSwaggerResponseList take the enclosing MultiVerb content-type slot as an additional poly-kinded parameter, and the separate '() and [Type] HasOpenApi (MultiVerb …) instances are replaced by a single instance.
  • Breaking: narrow the openapi-hs bound to >=5.0 && <5.1. Under PVP the breaking axis is A.B, so the previous <6 promised compatibility with an openapi-hs 5.1 that the policy explicitly permits to break this package.
  • Document the package's PVP versioning policy in the README.

5.0.0

  • Breaking: require openapi-hs >=5.0 && <6, resolved from its published Hackage release. openapi-hs 5 vendors the insertion-ordered map and set types it previously took from insert-ordered-containers, so this package no longer depends on insert-ordered-containers directly.
  • Breaking: code that imports Servant.OpenApi.Internal may need to replace Data.HashMap.Strict.InsOrd with Data.HashMap.Strict.InsOrd.Compat. The stable Servant.OpenApi generation API and generated schemas are unchanged.
  • Guard generated output with a byte-for-byte golden captured under openapi-hs-4.1.0 (test/golden/openapi-hs-4.1-gen-openapi.json). The document gen-openapi produces under openapi-hs-5.0.0 is identical to it, and still lints with 0 errors under vacuum.
  • Raise the lens lower bound to >=5.3.3.

4.1.0

  • Support servant's MultiVerb combinator (servant ≥ 0.20.3): toOpenApi now describes MultiVerb endpoints — one response object per status code, merging alternatives that share a code — and validateEveryToJSON / Servant.OpenApi.Test extract their body types. Ports biocad/servant-openapi3#59 without taking on a servant-server dependency.

4.0.0

  • Renamed to servant-openapi-hs, a fork of biocad/servant-openapi3 targeting OpenAPI 3.1.
  • Depend on openapi-hs instead of openapi3. The Data.OpenApi.* and Servant.OpenApi.* namespaces are unchanged. Generated documents now report "openapi": "3.1.0".
  • Builds and passes its test suite against openapi-hs. The port required only three library edits for OpenAPI-3.1 model changes — type_ now takes OpenApiTypeSingle OpenApiArray (the type-array model), and the OpenApi / PathItem record combiners set the new 3.1 fields webhooks and $ref (_pathItemRef).
  • Validate generated documents in two in-process layers beyond fixture equality: a round-trip decode through openapi-hs's version-enforcing FromJSON OpenApi, and validateEveryToJSON example-conformance.
  • Add a gen-openapi executable that prints a representative API's OpenAPI 3.1 document to stdout; its output lints with 0 errors under vacuum.
  • Require GHC 9.12.4 / 9.14.1; modernize to cabal-version: 3.0, build-type: Simple, and default-language: GHC2024.
  • Drop the cabal-doctest-based doctests test-suite (use cabal-docspec to run doctests instead).

Earlier history of the upstream servant-openapi3 package:

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.