OpenAPI Specification: Difference between revisions
(→paths) |
|||
(222 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
=External= | |||
* OpenAPI 3.1.0 Specification https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md | |||
* https://swagger.io/specification/ | |||
=Internal= | =Internal= | ||
* [[OpenAPI#OpenAPI_Specification|OpenAPI]] | |||
* [[OpenAPI#OpenAPI_Specification|OpenAPI | * [[API Concepts]] | ||
* [[REST and Hypermedia]] | |||
* [[Amazon_API_Gateway_Concepts#Integration_and_Swagger_Operations|Amazon API Gateway Integration]] | |||
* [[JSON_Schema#Overview|JSON Schema]] | |||
=Overview= | =Overview= | ||
The | OpenAPI Specification (OAS), formerly Swagger Specification, is an API description format and a specification standard for [[REST and Hypermedia#Overview|HTTP REST API]]s. The specification for an API can be expressed in a '''single file''', which provides the '''source of truth''' for the API, starting with the API design phase, then continuing with '''client''' and '''server code generation''', '''documentation''' and '''testing'''. The specification format is programming language agnostic, it is machine-readable and it can be used to generate code in different languages. API specifications are typically written in YAML or JSON. The latest version at the time of this writing is OpenAPI 3.1.0. | ||
The OpenAPI specification describes [[#Endpoint|endpoints]] and [[#Operation|operations]] for each endpoint, input and output [[#Parameter|parameters]] for each operation, [[#security|authentication methods]], contact information, licenses, etc. | |||
OpenAPI specification builds upon [[JSON_Schema#Overview|JSON Schema]]. | |||
=<span id='Endpoint'></span>Endpoints= | |||
An endpoint is exposed in the OpenAPI specification by its relative path, declared in the <code>[[#paths|paths]]</code> map. | |||
= | <font color=darkkhaki>Refactor this.</font> | ||
=Document Structure= | |||
<font size=-2> | |||
[[#openapi|openapi]]: 3.1.0 | |||
[[#info|info]]: | |||
[...] | |||
[[#servers|servers]]: | |||
===< | [...] | ||
[[#paths|paths]]: | |||
{{External| | [...] | ||
[[#components|components]]: | |||
[...] | |||
[[#webhooks|webhooks]]: | |||
[...] | |||
[[#security|security]]: | |||
[...] | |||
[[#tags|tags]]: | |||
[...] | |||
</font> | |||
==<tt>openapi</tt>== | |||
The string following the <code>openapi</code> element is the version number of the OpenAPI specification this document uses. | |||
==<tt>info</tt>== | |||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoObject}} | |||
<font size=-2> | |||
info: | |||
[[#title|title]]: OpenAPI Example | |||
[[#version|version]]: 0.2.0 | |||
[[#summary|summary]]: An OpenAPI example application | |||
[[#description|description]]: | |||
termsOfService: | |||
contact: | |||
license: | |||
</font> | |||
===<tt>title</tt>=== | |||
Required element. Represents the '''title of the API'''. When imported in AWS API Gateway, the title provides the API [[Amazon_API_Gateway_Concepts#API_Name|name]], unless the [[Amazon_API_Gateway_Deployment_with_CloudFormation#AWS::ApiGateway::RestApi|AWS::ApiGateway::RestApi]] resource explicitly specifies a title, in which case the title specified by AWS::ApiGateway::RestApi will take priority. | |||
===<tt>version</tt>=== | |||
Required element. Represents the version of the API document. It is different from <code>[[#openapi|openapi]]</code> version string. | |||
===<tt>summary</tt>=== | |||
A short summary of the API. | |||
===<tt>description</tt>=== | |||
A description of the API. CommonMark syntax may be used for rich text representation. | |||
==<tt>servers</tt>== | |||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject}} | |||
<syntaxhighlight lang='yaml'> | <syntaxhighlight lang='yaml'> | ||
servers: | |||
- url: https://petstore.swagger.io/v2 | |||
</syntaxhighlight> | </syntaxhighlight> | ||
== | ==<tt>paths</tt>== | ||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject}} | |||
{{External| | <font size=-2> | ||
paths: | paths: | ||
/a: | |||
summary: | |||
description: | |||
[[#Operations|get]]: [...] | |||
[[#Operations|put]]: [...] | |||
[[#Operations|post]]: [...] | |||
[[#Operations|delete]]: [...] | |||
[[#Operations|options]]: [...] | |||
[[#Operations|head]]: [...] | |||
[[#Operations|patch]]: [...] | |||
[[#Operations|trace]]: [...] | |||
servers: | |||
parameters: | |||
/b: | |||
[...] | |||
/c: | |||
[...] | |||
</font> | |||
Contains a map of relative '''paths''' to individual [[#Endpoint|endpoints]]. | |||
===Path=== | |||
For syntax of individual path specifications, see: | |||
{{Internal|OpenAPI Specification Path#Overview|OpenAPI Specification Path}} | |||
==<tt>components</tt>== | |||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject}} | |||
<font size=-2> | |||
components: | |||
[[#schemas|schemas]]: | |||
Pet: | |||
[...] | |||
Error: | |||
[...] | |||
</font> | |||
===<tt>schemas</tt>=== | |||
The <code>/components/schemas</code> section of the OpenAPI specification defines reusable objects. | |||
{{Internal|OpenAPI Specification Schemas#Overview|OpenAPI Specification Schemas}} | |||
==<tt>webhooks</tt>== | |||
A map of path item objects or reference objects. | |||
==<tt>security</tt>== | |||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject}} | |||
==<tt>tags</tt>== | |||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject}} | |||
=Data Types= | |||
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#data-types}} | |||
OAS data types are based on those supported by [https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1 JSON Schema Specification Draft 2020-12] | |||
{| class="wikitable" style="text-align: left;" | |||
! Type | |||
! Format | |||
! Comments | |||
|- | |||
| null || || A JSON "null" value. JSON Schema Specification type. | |||
|- | |||
| boolean || || A "true" or "false" value. JSON Schema Specification type. | |||
|- | |||
| object || || An unordered set of properties mapping a string to an instance. JSON Schema Specification type. | |||
|- | |||
| array || || An ordered list of instances. JSON Schema Specification type. | |||
|- | |||
| number || || An arbitrary-precision, base-10 decimal number value. JSON Schema Specification type. | |||
|- | |||
| string || || A string of Unicode code points. JSON Schema Specification type. | |||
|- | |||
| integer || int32 || Signed 32 bits. Introduced by OAS. | |||
|- | |||
| integer || int64 || Signed 64 bits (long). Introduced by OAS. | |||
|- | |||
| number || float || Introduced by OAS. | |||
|- | |||
| number || double || Introduced by OAS. | |||
|- | |||
| string || password || A hint to UIs to obscure input. Introduced by OAS. | |||
|- | |||
| string || date || See github.com/oapi-codegen/runtime/types/date.go | |||
|- | |||
| string || email || See github.com/oapi-codegen/runtime/types/email.go | |||
|- | |||
| string || file || See github.com/oapi-codegen/runtime/types/file.go | |||
|- | |||
| string || uuid || See github.com/oapi-codegen/runtime/types/uuid.go | |||
|- | |||
|} | |||
=<tt>$ref</tt>= | |||
=OpenAPI Operation Declaration and Implementation Examples= | |||
{{Internal|OpenAPI_Specification_Path#Operation_Declaration_and_Implementation_Examples|OpenAPI Examples}} |
Latest revision as of 03:51, 27 January 2024
External
- OpenAPI 3.1.0 Specification https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
- https://swagger.io/specification/
Internal
Overview
OpenAPI Specification (OAS), formerly Swagger Specification, is an API description format and a specification standard for HTTP REST APIs. The specification for an API can be expressed in a single file, which provides the source of truth for the API, starting with the API design phase, then continuing with client and server code generation, documentation and testing. The specification format is programming language agnostic, it is machine-readable and it can be used to generate code in different languages. API specifications are typically written in YAML or JSON. The latest version at the time of this writing is OpenAPI 3.1.0.
The OpenAPI specification describes endpoints and operations for each endpoint, input and output parameters for each operation, authentication methods, contact information, licenses, etc.
OpenAPI specification builds upon JSON Schema.
Endpoints
An endpoint is exposed in the OpenAPI specification by its relative path, declared in the paths
map.
Refactor this.
Document Structure
openapi: 3.1.0 info: [...] servers: [...] paths: [...] components: [...] webhooks: [...] security: [...] tags: [...]
openapi
The string following the openapi
element is the version number of the OpenAPI specification this document uses.
info
info: title: OpenAPI Example version: 0.2.0 summary: An OpenAPI example application description: termsOfService: contact: license:
title
Required element. Represents the title of the API. When imported in AWS API Gateway, the title provides the API name, unless the AWS::ApiGateway::RestApi resource explicitly specifies a title, in which case the title specified by AWS::ApiGateway::RestApi will take priority.
version
Required element. Represents the version of the API document. It is different from openapi
version string.
summary
A short summary of the API.
description
A description of the API. CommonMark syntax may be used for rich text representation.
servers
servers:
- url: https://petstore.swagger.io/v2
paths
paths: /a: summary: description: get: [...] put: [...] post: [...] delete: [...] options: [...] head: [...] patch: [...] trace: [...] servers: parameters: /b: [...] /c: [...]
Contains a map of relative paths to individual endpoints.
Path
For syntax of individual path specifications, see:
components
components: schemas: Pet: [...] Error: [...]
schemas
The /components/schemas
section of the OpenAPI specification defines reusable objects.
webhooks
A map of path item objects or reference objects.
security
tags
Data Types
OAS data types are based on those supported by JSON Schema Specification Draft 2020-12
Type | Format | Comments |
---|---|---|
null | A JSON "null" value. JSON Schema Specification type. | |
boolean | A "true" or "false" value. JSON Schema Specification type. | |
object | An unordered set of properties mapping a string to an instance. JSON Schema Specification type. | |
array | An ordered list of instances. JSON Schema Specification type. | |
number | An arbitrary-precision, base-10 decimal number value. JSON Schema Specification type. | |
string | A string of Unicode code points. JSON Schema Specification type. | |
integer | int32 | Signed 32 bits. Introduced by OAS. |
integer | int64 | Signed 64 bits (long). Introduced by OAS. |
number | float | Introduced by OAS. |
number | double | Introduced by OAS. |
string | password | A hint to UIs to obscure input. Introduced by OAS. |
string | date | See github.com/oapi-codegen/runtime/types/date.go |
string | See github.com/oapi-codegen/runtime/types/email.go | |
string | file | See github.com/oapi-codegen/runtime/types/file.go |
string | uuid | See github.com/oapi-codegen/runtime/types/uuid.go |