OpenAPI Specification Schemas: Difference between revisions
(→Schema) |
|||
Line 34: | Line 34: | ||
</font> | </font> | ||
A Go type is generated only if a schema is referred from the specification with <code>schema.[[OpenAPI_Specification#$ref|$ref]]</code>. If the type is declared, but not referred, no code will be generated for it. | |||
==Schema Name== | ==Schema Name== | ||
Revision as of 02:26, 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: properties: color: type: string size: type: integer format: int32 weight: type: number format: double required: - color - size - weight format: description: discriminator: externalDocs:
A Go type is generated 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.
Schema Name
type
One of the supported data types.
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:
type: string
size:
type: integer
format: int32
weight:
type: number
format: double
required
An array with the name of the required fields:
MyType:
[...]
required:
- color
- size:
- weight
format
Code Generation
Currently, this section only refers to oapi-codegen
and Go code generation.
The types and the fields are implicitly exported, they start with upper case characters, even if they are declared lower case characters.
Example
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
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
Composition
allOf
Polymorphism
discriminator