OpenAPI Specification Schemas: Difference between revisions
(→anyOf) |
(→not) |
||
| Line 216: | Line 216: | ||
==<tt>not</tt>== | ==<tt>not</tt>== | ||
{{External|https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/}} | |||
=<tt>allOf</tt>= | =<tt>allOf</tt>= | ||
Revision as of 16:57, 26 January 2024
External
- https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject
- https://tools.ietf.org/html/draft-bhutton-json-schema-00
- https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00
Internal
Overview
The /components/schemas section of the OpenAPI specification defines reusable types that are used as input and output data types. These types can represent objects, but also primitives and arrays. The specification is based on JSON Schema Specification Draft 2020-12. A client or server code generator creates programming language types from these schemas.
This article is annotated with details related to how oapi-codegen generates Go code.
Schema
SchemaName type: object|string|integer|number|array|boolean format: int32|int64|float|double|password|date|email|file|uuid properties: color: type: string size: type: integer format: int32 minimum: 0 maximum: 100 weight: type: number format: double required: - color - size - weight description: discriminator: externalDocs: example:
A Go type is generated for a schema only if a schema is referred from the specification with schema.$ref. If the type is declared, but not referred, no code will be generated for it. Alias types are generated: a custom-named typed for integer or string can be generated.
Both the types and their fields are implicitly exported with oapi-codegen, they get names that start with upper case characters, even if they are declared with lower case characters in the OpenAPI specification.
Schema Name
type
One of the supported data types ("object", "string", "integer", "number", "array", "boolean", etc.):
format
One of the supported formats ( "int32", "int64", "float", "double", "password", "date", "email", etc.):
minimum
maximum
properties
For a schema of type object, properties contains a map whose keys are the names of the fields. Each map element must mandatorily include type and optionally format:
MyType:
type: object
properties:
color: # 'color' is the name of a field of MyType
type: string
size: # 'size' is the name of a field of MyType
type: integer
format: int32
minimum: 0
weight: # 'weight' is the name of a field of MyType
type: number
format: double
required
An array with the name of the required fields:
MyType:
[...]
required:
- color
- size
# weight is not required, it will be represented as a pointer
If a field is declared as "required", oapi-codegen will generate the struct corresponding to the schema with a value for that field. If the field is not among the required fields, the struct will carry a pointer instead of a the value, presumably so it can be set to nil.
type MyType struct {
Color string `json:"color"` // required field
Size int32 `json:"size"` // required field
Weight *float64 `json:"weight,omitempty"` // not required field
}
description
discriminator
TODO. Also see Polymorphism below.
externalDocs
example
type: object
properties:
id:
type: integer
format: int64
name:
type: string
required:
- name
example:
name: Blue
id: 1
Composition
Types can be composed with $ref:
components:
schemas:
Person:
type: object
properties:
firstName:
type: string
lastName:
type: string
address:
$ref: "#/components/schemas/Address"
required:
- firstName
- lastName
- address
Address:
type: object
properties:
street:
type: string
city:
type: string
zip:
type: integer
format: int32
required:
- street
- city
- zip
The corresponding generated code:
type Person struct {
Address Address `json:"address"`
FirstName string `json:"firstName"`
LastName string `json:"lastName"`
}
type Address struct {
City string `json:"city"`
Street string `json:"street"`
Zip int32 `json:"zip"`
}
A <String,String> Map
components:
schemas:
AMap:
type: object
additionalProperties:
type: string
The corresponding generated code:
type AMap map[string]string
A <String,Object> Map
components:
schemas:
AMap:
type: object
additionalProperties:
$ref: "#/components/schemas/MapElement"
MapElement:
type: object
properties:
color:
type: string
size:
type: integer
required:
- color
- size
The corresponding generated code:
type AMap map[string]MapElement
type MapElement struct {
Color string `json:"color"`
Size int `json:"size"`
}
Combining Schemas
OpenAPI 3.0 provides a set of keywords that can be used to combine schemas. These keywords can be used to compose complex schemas from components, or validate against multiple criteria. These keywords are allOf, oneOf, anyOf and not.
allOf
allOf takes an array of object definitions that are used for independent validation - they can be used as individual types - and composes them in a single object. This is a simple composition model, it does imply hierarchy between models. To create a hierarchy, use the discriminator field. To be valid against allOf, the data provided by the client must be valid against all of the given subschemas.
oneOf
anyOf
not
allOf
TODO:
- https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
- https://www.speakeasyapi.dev/post/openapi-tips-oneof-allof-anyof
components:
schemas:
Pet:
allOf:
- $ref: '#/components/schemas/NewPet'
- type: object
required:
- id
properties:
id:
type: integer
format: int64
NewPet:
type: object
required:
- name
properties:
name:
type: string
tag:
type: string
anyOf
oneOf
not
Polymorphism
See discriminator above.