@hackage / servant-openapi-hs

servant-openapi-hs

Generate an OpenAPI 3.1 specification for your Servant API, and partially test that the API conforms to its specification.

Fork notice. servant-openapi-hs is a fork of biocad/servant-openapi3, which targets OpenAPI 3.0. This fork retargets it at OpenAPI 3.1 by building on openapi-hs (a fork of biocad/openapi3) instead of openapi3. The Haskell module namespace is unchanged (Servant.OpenApi.*), and because openapi-hs keeps the Data.OpenApi.* namespace, migrating is usually just a dependency-name swap: servant-openapi3 → servant-openapi-hs and openapi3 → openapi-hs. The fork keeps the upstream BSD-3-Clause license and copyright.

Motivation

OpenAPI is a language-agnostic format for describing and documenting HTTP APIs. This package derives an OpenAPI 3.1 specification directly from a Servant API type, so the description stays in sync with the server, and provides combinators to test that handlers conform to the generated schema.

A generated specification can then be used to

• display interactive documentation in any OpenAPI 3.1 viewer;
• generate clients and servers in many languages with OpenAPI Generator;
• and many other things across the OpenAPI tooling ecosystem.

Installation

Pre-release. The first Hackage release is still in preparation. Until it is published, depend on this repository directly (see Building from source below); the instructions in this section describe the package once it is on Hackage.

Add servant-openapi-hs to your package's build-depends:

build-depends: servant-openapi-hs

Its OpenAPI 3.1 data model comes from openapi-hs, which is pulled in automatically as a transitive dependency.

Import the umbrella module:

import Servant.OpenApi

Requires GHC 9.12.4 or 9.14.1.

Building from source. Until the first Hackage release, depend on this repository directly by adding a source-repository-package stanza for servant-openapi-hs to your cabal.project:

source-repository-package
    type:     git
    location: https://github.com/shinzui/servant-openapi-hs.git
    tag:      <commit-sha>

Its openapi-hs dependency resolves from Hackage automatically.

Usage

Derive an OpenAPI 3.1 document from a Servant API type with toOpenApi:

import Data.Aeson (encode)
import Data.OpenApi (OpenApi)
import Data.Proxy (Proxy (..))
import Servant.OpenApi (toOpenApi)

spec :: OpenApi
spec = toOpenApi (Proxy :: Proxy MyApi)
-- encode spec  ==>  {"openapi":"3.1.0", ...}

A runnable example lives in app/GenOpenApi.hs, built as the gen-openapi executable, which prints a complete Todo-CRUD document:

cabal run gen-openapi > openapi.json

The full API surface is unchanged from upstream; see the Haddock documentation. Generated specifications can be explored interactively in any OpenAPI 3.1 viewer or editor.

Validation

Generated documents are checked at three levels:

1. Round-trip — the test suite decodes each generated document back through openapi-hs's FromJSON OpenApi, which rejects any openapi version outside 3.1.0 … 3.1.1, then compares the result for semantic equality.

2. Example-conformance — Servant.OpenApi.Test.validateEveryToJSON checks that random values of each response type validate against the generated schema.

3. Authoritative conformance — the gen-openapi output lints cleanly under vacuum:

   cabal run gen-openapi > openapi.json
   nix run nixpkgs#vacuum-go -- lint -d openapi.json

Contributing

Bug reports, fixes, documentation improvements, and other contributions are welcome. Please open an issue or pull request on the GitHub issue tracker.

License

servant-openapi-hs retains the original BSD-3-Clause license of the upstream servant-openapi3 project, including its copyright. See the LICENSE file for the full text; this fork's changes are released under the same terms.

Originally derived from work by the Servant contributors (David Johnson, Nickolay Kudasov, Maxim Koltsov, and others).