BSD-3-Clause licensed by Nickolay Kudasov
Maintained by [email protected]
This version can be pinned in stack with:swagger2-2.1@sha256:5588b5f9ac5019180300c6bad9cb491f80bcff3f714d89e89ffb6ddc3aa6ac9c,3093

Module documentation for 2.1

  • Data
    • Data.Swagger
      • Data.Swagger.Declare
      • Data.Swagger.Internal
        • Data.Swagger.Internal.AesonUtils
        • Data.Swagger.Internal.ParamSchema
        • Data.Swagger.Internal.Schema
          • Data.Swagger.Internal.Schema.Validation
        • Data.Swagger.Internal.Utils
      • Data.Swagger.Lens
      • Data.Swagger.Operation
      • Data.Swagger.ParamSchema
      • Data.Swagger.Schema
        • Data.Swagger.Schema.Validation
      • Data.Swagger.SchemaOptions


Hackage Build Status Stackage LTS Stackage Nightly

Swagger 2.0 data model.

The original Swagger 2.0 specification is available at


This library is inteded to be used for decoding and encoding Swagger 2.0 API specifications as well as manipulating them.

Please refer to haddock documentation.

Some examples can be found in examples/ directory.

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


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

Please report bugs via the github issue tracker.

GetShopTV Team



  • Major changes:
    • Use InsOrdHashMap to preserve insertion order for endpoints and definitions (see #56);
    • Add support for GHC 8.0 (see #65).


  • Fixes:
    • Fix additionalProperties to allow references;
    • Fix ToSchema instances for Map and HashMap (prevent infinite recursion for recursive values).


  • Fixes:
    • Re-export Pattern synonym from Data.Swagger;
    • Documentation fixes.


  • Major changes:

    • GHC 7.8 support (see #49);
    • Switch to classy field lenses (see #41);
    • Add Data.Swagger.Schema.Validation (see #18);
    • Add Data.Swagger.Operation with helpers (see #50);
    • Add IsString instances for some types (see #47);
    • Add helpers to sketch Schema from JSON (see #48).
  • Minor changes:

    • Make NamedSchema a data rather than type (see #42);
    • Change Definitions to Definitions Schema;
    • Add schema templates for "binary", "byte" and "password" formats (see 63ed597);
    • Add Monoid instance for Contact;
    • Change tags to be Set rather than list.
  • Fixes:

    • Fix schema for () and nullary constructors (see ab65c4a);
    • Fix Operation FromJSON instance to allow missing tags and parameters properties.


  • Minor changes:

    • Change _SwaggerItemsPrimitive type from a Prism' to a more restrictive Review-like Optic'.
  • Fixes:

    • Fix build for GHC 8.0-rc1.


  • Minor changes (see #36):

    • Change default ToSchema instance for unit data types (i.e. types with one nullable constructor like data Unit = Unit): now these types are treated like sum types with only one alternative;
    • Add generic ToParamSchema instance for unit data types;
    • Add items: [] to schema for () (making it a valid schema).
  • Fixes:

    • Do not omit items: [] from Schema JSON;
    • Do not generate unused definitions for nested newtypes (see #38).


  • Fixes:
    • CollectionFormat Param -> CollectionFormat ParamOtherSchema; this change was necessary after putting CollectionFormat to SwaggerItems.


  • Major changes:

    • Put CollectionFormat in one place (see 3cc860d).
  • Minor changes:

    • Use Swagger formats for Int32, Int64, Float, Double, Day and ZonedTime (see #32);
    • Export HeaderName, TagName, HttpStatusCode type synonyms;
    • Add ToParamSchema instances for [a], Set a and HashSet a;
    • Add Monoid instances for Header and Example.
  • Fixes:

    • Use overwrite strategy for HashMap SwaggerMonoid instances by default.


  • Major changes:

    • Add Data and Typeable instances for Data.Swagger types;
    • Merge ParamType/ItemsType/SchemaType into SwaggerType GADT;
    • Merge collection format types into CollectionFormat GADT;
    • Introduce SwaggerItems GADT, replacing Items and SchemaItems in ParamSchema (see #24);
    • Move type, format and items fields to ParamSchema (former SchemaComon);
    • Prepend reference path automatically (see commit 49d1fad) and thus remove "#/definitions/" from user code, leaving much clearer Reference "Name";
    • Change Data.Swagger.Schema (see #19):
      • Change the only method of ToSchema to declareNamedSchema which should produce a NamedSchema along with a list of schema definitions used to produce it;
      • Add declareSchema, declareSchemaRef;
      • Replace genericTo* helpers with genericDeclare* helpers;
      • Add paramSchemaTo[Named]Schema helpers to facilitate code reuse for primitive schemas;
      • Add helpers for inlining Schema references dynamically (see #23);
    • Add ToParamSchema class (see #17) with
      • generic default implementation and
      • instances for some base types compliant with http-api-data instances;
    • Add Data.Swagger.Declare module with
      • DeclareT monad transformer;
      • MonadDeclare type class;
      • various helpers;
    • Rename parameter-related types:
      • Parameter -> Param;
      • ParameterSchema -> ParamAnySchema;
      • ParameterOtherSchema -> ParamOtherSchema;
      • ParameterLocation -> ParamLocation;
      • SchemaCommon -> ParamSchema;
      • parameter* fields renamed to param* fields;
      • schemaCommon* fields renamed to paramSchema* fields;
      • HasSchemaCommon -> HasParamSchema.
  • Minor changes:

    • Replace TH-generated JSON instances with Generic-based (see #25);
    • Drop template-haskell dependency;
    • Omit empty array/object properties from toJSON output (#22);
    • Remove minLength property from schemas for time types;
    • Move SchemaOptions to Data.Swagger.SchemaOptions;
    • Remove useReferences from SchemaOptions (see #23);
    • Place all internal submodules under Data.Swagger.Internal;
    • Better documentation (see #26).


  • Fixes:
    • Use PackageImports for Data.HashSet to avoid test failure on stackage (see #15);
    • Add an upper version bound for aeson due to aeson- bug (see bos/aeson#293);
    • Switch to Cabal-based multi GHC Travis config.


  • Remove Swagger/swagger prefixes;
  • Add ToSchema type class with default generic implementation;
  • Add configurable generic ToSchema helpers;
  • Add doctest test suite;
  • Fixes:
    • Fix HasSchemaCommon instance for Schema;
    • Change minimum, maximum and multipleOf properties to be any number, not necessarily an integer;
    • Fix all warnings.


  • Fixes:
    • Fix SwaggerMonoid Text instance;
    • Wrap Bool in Maybe everywhere;
    • These changes make all Data.Swagger Monoid instances obey monoid laws (previously right identity law was broken by some instances).


  • Add Data.Swagger.Lens;
  • Support references;
  • Fixes:
    • Fix FromJSON SwaggerHost instance;
    • Add missing Maybes for field types;
    • Decode petstore swagger.json successfully.