openapi3
OpenAPI 3.0 data model
https://github.com/biocad/openapi3
LTS Haskell 22.37: | 3.2.4@rev:2 |
Stackage Nightly 2024-10-11: | 3.2.4@rev:2 |
Latest on Hackage: | 3.2.4@rev:2 |
openapi3-3.2.4@sha256:780f50a7538a02a83ea21db26f5c69578800c5f6895baecb98013b69b0d0f1f8,4943
Module documentation for 3.2.4
OpenApi 3
OpenAPI 3.0 data model.
The original OpenAPI 3.0 specification is available at http://swagger.io/specification/.
This package is heavily based on excellent work on Swagger 2.0 at https://github.com/GetShopTV/swagger2.
Usage
This library is intended to be used for decoding and encoding OpenApi 3.0.3 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.
Contributing
We are happy to receive bug reports, fixes, documentation enhancements, and other improvements.
Please report bugs via the github issue tracker.
GetShopTV Team
Biocad Team
Changes
Unreleased
3.2.4
- Give
title
to sub schemas of sum types #88.
3.2.3
- Fix generation of
allOf
/oneOf
schemas when variants are not objects #49. - Support parsing OpenAPI 3.0.1, 3.0.2, 3.0.3 versions #68.
- Support GHC-9.4 #61.
- Output
scopes
in schema even if empty #65. - Fix
mtl-2.3
compatibility #60.
3.2.2
- Fix bug with infinite recursion in GToSchema #37.
3.2.1
- Support aeson-2.0.3.
- Support GHC-9.2 (doctests still fail).
3.2.0
3.1.0
- Use
format: date-time
forToParamSchema ZonedTime
instance (see #20). - Support generating schema for any polymorphic types via
Typeable
(see #19). - Allow
hashable-1.3.1
, prettify doctests (see #18).
3.0.2.0
- Fix definition for HTTP security scheme (see #10);
- Fix error message in
exclusiveMaximum
/exclusiveMinimum
validation (see #15);
3.0.1.0
- Support polymorphic types in schema generator.
3.0.0
- Switch to OpenAPI 3.0 specification.
2.6.1
- More GHC-8.10 related cleanup, tighten lower bound on some dependencies. (see #216);
- Add “format” field for uint32 and uint64 (see #215);
2.6
- GHC 8.10 support (see #210);
- Move
aeson-pretty
to other dependencies (see #206); - Merge OAuth2 scopes (see #151);
2.5
Highlights:
- Add instance for
TimeOfDay
(see #196); - Add support for
optics
(see #200); - Slightly better validation errors (see #195);
Fixes and minor changes:
- Minor cleanup (see #194);
- Allow base-4.13 and other GHC-8.8 related stuff (see #198);
- Fix
stack.yaml
(see #201);
2.4
- Allow hashable-1.3, semigroups-0.19, network-3.1, time-1.9, generics-sop-0.5
- Tags aren’t sorted (see #165)
- Schema type is optional (see #138, #164)
- Take concrete ‘Proxy’ as argument (see #180)
- GHC-8.8 preparations
2.3.1.1
- Allow
network-3.0
2.3.1
- Add a quickcheck generator for aeson Values that match a swagger schema (see #162)
- Add
ToParamSchema
instance forSetCookie
(see #173) - Make nullary schemas valid (see #168)
2.3.0.1
- Support GHC-8.6
2.3
Major changes:
- Add support for
additionalProperties
withBool
value (see #159); - Add
ToSchema
Object
instance (for aeson’sObject
) (seed72466a
);
Dependencies and CI:
- Aeson 1.4 (see #158);
- Update .travis.yml (see #160);
- Allow network 2.7 (see #155);
- Allow lens-4.17 (see #161);
2.2.2
- Add
ToSchema Version
instance - Use base-compat-batteries (0.10)
- PVP bounds
2.2.1
- Add
Semigroup
instances - GHC-8.4 compatibility
- `Schema (NonEmpty a) instance (see #141)
- Fix optional property for unary records (see #142)
- Add
fromAesonOptions
helper (see #146) - Fix non-termination when using
datatypeNameModifier
with recursive data types (see #132)
2.2
- Treat unknown properties as validation errors in
validateToJSON
(see #126); - Add
validateJSON
andvalidateJSONWithPatternChecker
to validate JSONValue
againstSchema
without classes (see #126); - Add more
Schema
helpers (see #126):genericNameSchema
— to give a custom schemaGeneric
-based name;genericDeclareNamedSchemaNewtype
— to deriveNamedSchema
fornewtype
s;declareSchemaBoundedEnumKeyMapping
— to derive more specificSchema
for maps withBounded
Enum
keys;
- Add a few tests with invalid
Schema
.
2.1.6
- Add
ToParamSchema
andToSchema
instances forFixed
(see #121) andNatural
(see #123); - Fix instance for
NominalDiffTime
(see #121); - Fix build for
aeson-1.2.2.0
(see #125).
2.1.5
- Type error by default when deriving Generic-based instances for mixed sum types (see #118);
- Adjust
allOf
to accept referenced schemas (see #119); - Add instances for
Identity
(see #116); - Add Gitter chat badge (see #114).
2.1.4.1
- GHC-8.2 support (see #95, #106 and #108);
- Documentation corrections (see #105);
- Allow
generics-sop-0.3
(see #102); - Fix
ToSchema
example in docs (see #104).
2.1.4
2.1.3
- Add
UUID
instances (see #81). - Add
TypeError
ToSchema
andToParamSchema ByteString
instances (see #78) - Improve documentation for generic sum type instance derivation (see #75)
- Compile warning free (see #82)
2.1.2.1
- Bug fix previous release
2.1.2
- Minor changes:
- Support
aeson-1.0.0.0
(see #70).
- Support
2.1.1
- Minor changes:
- Proper
Schema
examples forChar
,Day
,LocalTime
,ZonedTime
andUTCTime
.
- Proper
2.1
- Major changes:
2.0.2
- Fixes:
- Fix
additionalProperties
to allow references; - Fix
ToSchema
instances forMap
andHashMap
(prevent infinite recursion for recursive values).
- Fix
2.0.1
- Fixes:
- Re-export
Pattern
synonym fromData.Swagger
; - Documentation fixes.
- Re-export
2.0
-
Major changes:
-
Minor changes:
-
Fixes:
- Fix schema for
()
and nullary constructors (see ab65c4a); - Fix
Operation
FromJSON
instance to allow missingtags
andparameters
properties.
- Fix schema for
1.2.1
-
Minor changes:
- Change
_SwaggerItemsPrimitive
type from aPrism'
to a more restrictiveReview
-likeOptic'
.
- Change
-
Fixes:
- Fix build for GHC 8.0-rc1.
1.2
-
Minor changes (see #36):
- Change default
ToSchema
instance for unit data types (i.e. types with one nullable constructor likedata 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).
- Change default
-
Fixes:
- Do not omit
items: []
fromSchema
JSON; - Do not generate unused definitions for nested
newtype
s (see #38).
- Do not omit
1.1.1
- Fixes:
CollectionFormat Param
->CollectionFormat ParamOtherSchema
; this change was necessary after puttingCollectionFormat
toSwaggerItems
.
1.1
-
Major changes:
- Put
CollectionFormat
in one place (see3cc860d
).
- Put
-
Minor changes:
- Use Swagger formats for
Int32
,Int64
,Float
,Double
,Day
andZonedTime
(see #32); - Export
HeaderName
,TagName
,HttpStatusCode
type synonyms; - Add
ToParamSchema
instances for[a]
,Set a
andHashSet a
; - Add
Monoid
instances forHeader
andExample
.
- Use Swagger formats for
-
Fixes:
- Use overwrite strategy for
HashMap
SwaggerMonoid
instances by default.
- Use overwrite strategy for
1.0
-
Major changes:
- Add
Data
andTypeable
instances forData.Swagger
types; - Merge
ParamType
/ItemsType
/SchemaType
intoSwaggerType
GADT; - Merge collection format types into
CollectionFormat
GADT; - Introduce
SwaggerItems
GADT, replacingItems
andSchemaItems
inParamSchema
(see #24); - Move type, format and items fields to
ParamSchema
(formerSchemaComon
); - Prepend reference path automatically (see commit 49d1fad)
and thus remove
"#/definitions/"
from user code, leaving much clearerReference "Name"
; - Change
Data.Swagger.Schema
(see #19):- Change the only method of
ToSchema
todeclareNamedSchema
which should produce aNamedSchema
along with a list of schema definitions used to produce it; - Add
declareSchema
,declareSchemaRef
; - Replace
genericTo*
helpers withgenericDeclare*
helpers; - Add
paramSchemaTo[Named]Schema
helpers to facilitate code reuse for primitive schemas; - Add helpers for inlining
Schema
references dynamically (see #23);
- Change the only method of
- 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 withDeclareT
monad transformer;MonadDeclare
type class;- various helpers;
- Rename parameter-related types:
Parameter
->Param
;ParameterSchema
->ParamAnySchema
;ParameterOtherSchema
->ParamOtherSchema
;ParameterLocation
->ParamLocation
;SchemaCommon
->ParamSchema
;parameter*
fields renamed toparam*
fields;schemaCommon*
fields renamed toparamSchema*
fields;HasSchemaCommon
->HasParamSchema
.
- Add
-
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 fortime
types; - Move
SchemaOptions
toData.Swagger.SchemaOptions
; - Remove
useReferences
fromSchemaOptions
(see #23); - Place all internal submodules under
Data.Swagger.Internal
; - Better documentation (see #26).
- Replace TH-generated JSON instances with
0.4.1
- Fixes:
- Use
PackageImports
forData.HashSet
to avoid test failure on stackage (see #15); - Add an upper version bound for
aeson
due toaeson-0.10.0.0
bug (see bos/aeson#293); - Switch to Cabal-based multi GHC Travis config.
- Use
0.4
- 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 forSchema
; - Change
minimum
,maximum
andmultipleOf
properties to be any number, not necessarily an integer; - Fix all warnings.
- Fix
0.3
- Fixes:
- Fix
SwaggerMonoid Text
instance; - Wrap
Bool
inMaybe
everywhere; - These changes make all
Data.Swagger
Monoid
instances obey monoid laws (previously right identity law was broken by some instances).
- Fix
0.2
- Add
Data.Swagger.Lens
; - Support references;
- Fixes:
- Fix
FromJSON SwaggerHost
instance; - Add missing
Maybe
s for field types; - Decode petstore
swagger.json
successfully.
- Fix