OpenAPI Specification: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(164 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 Specification]]
* [[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 document addresses both OpenAPI 2.0 and OpenAPI 3.0. The differences will be emphasized.
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.


=Swagger Java Model=
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.


[[File:SwaggerJavaModel.png]]
OpenAPI specification builds upon [[JSON_Schema#Overview|JSON Schema]].


=<tt>info</tt>=
=<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.


==<tt>title</tt>==
<font color=darkkhaki>Refactor this.</font>


When imported in AWS API Gateway, the title provides the API [[Amazon_API_Gateway_Concepts#API_Name|name]].
=Document Structure=
 
<font size=-2>
=<tt>paths</tt>=
[[#openapi|openapi]]: 3.1.0
 
[[#info|info]]:
Contains a map of [[#path|paths]].
  [...]
 
[[#servers|servers]]:
==Path==
    [...]
 
[[#paths|paths]]:
The path is designated by its literal, as key in the [[#paths|paths]] map. Each path contains zero or one of these [[#Operation|operations]]: GET, POST, PUT, HEAD, DELETE, PATCH, OPTIONS, a list of [[#Parameter|Parameters]] and a map of vendor extensions.
    [...]
 
[[#components|components]]:
===<span id='Operations'></span>Operation===
    [...]
 
[[#webhooks|webhooks]]:
{{External|[https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject OpenAPI 2.0 Operation]}}
    [...]
 
[[#security|security]]:
  paths:
    [...]
   /a:
[[#tags|tags]]:
    get:
    [...]
      parameters:
</font>
        - name: 'test'
==<tt>openapi</tt>==
          in: query
The string following the <code>openapi</code> element is the version number of the OpenAPI specification this document uses.
          type: 'string'
==<tt>info</tt>==
      [[#responses|responses]]:
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoObject}}
        200:
<font size=-2>
          schema:
  info:
            $ref: '#/definitions/Empty'
   [[#title|title]]: OpenAPI Example
definitions:
  [[#version|version]]: 0.2.0
   Empty:
  [[#summary|summary]]: An OpenAPI example application
    type: object
  [[#description|description]]:
 
   termsOfService:
Also see: {{Internal|Amazon_API_Gateway_Concepts#Integration_and_Swagger_Operations|Amazon API Gateway Integration}}
  contact:
 
  license:
Valid operation keys:
</font>
* get
===<tt>title</tt>===
* put
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.
* post
===<tt>version</tt>===
* delete
Required element. Represents the version of the API document. It is different from <code>[[#openapi|openapi]]</code> version string.
* options
===<tt>summary</tt>===
* head
A short summary of the API.
* patch
===<tt>description</tt>===
 
A description of the API. CommonMark syntax may be used for rich text representation.
====<tt>parameters</tt>====
==<tt>servers</tt>==
 
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject}}
Contains a list of in-line declaration of [[#Parameter|parameters]] (parameter objects) and references.
<syntaxhighlight lang='yaml'>
 
servers:
====<tt>responses</tt>====
  - url: https://petstore.swagger.io/v2
 
</syntaxhighlight>
{{External|[https://swagger.io/specification/#responsesObject responses Object]}}
 
A required element that list all possible [[#Response|responses]] that are returned from executing this operations. The element must contain at least one response code. The container  maps a HTTP response code to the expected response. The definition is not expected to cover all possible HTTP response codes, because they may not be known in advance. However, the definition should cover a successful operation response and any known errors. The "default" map key may be used as a default response object for all HTTP codes that are not covered individually in the definition.  
 
paths:
  /a:
    get:
      <font color=teal>'''responses'''</font>:
        <font color=teal>'''200</font>:
          ...
        <font color=teal>'''default</font>:
          ...


====<tt>produces</tt>====
==<tt>paths</tt>==
 
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject}}
Contains a list of media types this operation can respond with. The list specified at operation level overrides the list specified on global level. <font color=darkgray>Document that.</font>
<font size=-2>
  paths:
  paths:
   /a:
   /a:
    get:
    summary:
      <font color=teal>'''produces'''</font>:
    description:  
        - application/json
    [[#Operations|get]]: [...]
 
     [[#Operations|put]]: [...]
Note that Swagger Core Operation.getProduces() may return null.
    [[#Operations|post]]: [...]
 
    [[#Operations|delete]]: [...]
====<tt>consumes</tt>====
     [[#Operations|options]]: [...]
 
    [[#Operations|head]]: [...]
Note that Swagger Core Operation.getConsumes() may return null.
    [[#Operations|patch]]: [...]
 
    [[#Operations|trace]]: [...]
====<span id='Tags'></span><tt>tags</tt>====
    servers:
 
    parameters:
{{External|[https://swagger.io/docs/specification/grouping-operations-with-tags/ Grouping Operations with Tags]}}
   /b:
 
     [...]
Each API [[#Operation|operation]] can be annotated with a list of tags. Tagged operations may be handled differently by tools and libraries. Optionally, each tag can get a "description" and an "externalDocs" in the global "tags" section on the root level. The tag names here should match those used in operations. The tag order in the global tags section also controls the default sorting in the UI - at least, for Swagger UI. It is possible to use a tag at operation level even if it is not specified on the root level.
  /c:
 
     [...]
<font color=teal>'''tags'''</font>:
</font>
  -name: tag-a
Contains a map of relative '''paths''' to individual [[#Endpoint|endpoints]].  
    description: Something that would shed light on tag-a semantics
    externalDocs:
    url: http&#58;//example.com/my-docs/tag-a.html
   
paths:
  /a:
     get:
      <font color=teal>'''tags'''</font>:
        - tag-a
        - other-tag
 
===Path Templating===
 
Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using [[#Path_Parameter|path parameters]].
 
=Parameter=
 
{{External|[https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject Parameter Object]}}
 
There are five parameter types: [[#Path_Parameter|path]], [[#Query_Parameter|query]], [[#Request_Header|request header]], [[#Request_Body|request body]] and [[#Form|form]] parameters. All parameters use the following fields in their declaration:
* <span id='parameter_name'></span>'''name'''
* <span id='parameter_in'></span>'''in'''
* <span id='parameter_required'></span>'''required'''
* <span id='parameter_description'></span>'''description'''
* <span id='parameter_type'></span>'''type'''. If "in" is any value other than "body", the type is required, and it is limited to simple types, not object. The value must be one of the following: "string", "number", "integer", "boolean", "array" or "file".
 
==Path Parameter==
 
Path parameters are used together with [[#Path_Templating|path templating]] where  the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. A path parameter is required. Example:
/query/{'''id'''}
Representation:
paths:
  /query/{id}:
     ''operation'':
        parameters:
          - [[#parameter_name|name]]: id
            [[#parameter_in|in]]: <font color=teal>'''path'''</font>
            [[#parameter_type|type]]: string
            [[#parameter_required|required]]: true
            [[#parameter_description|description]]: "some description"
 
Also see: {{Internal|REST_and_Hypermedia#Path_Parameter|REST Path Parameters}}
 
==Query Parameter==
Also see: {{Internal|REST_and_Hypermedia#Query_Parameter|REST Query Parameters}}
 
==Request Header==
 
Also see: {{Internal|REST_and_Hypermedia#Request_Header|REST Request Headers}}
 
==Request Body==
 
Also see: {{Internal|REST_and_Hypermedia#Request_Body|REST Request Body}}
 
==Form==
 
=Response=
 
{{External|[https://swagger.io/specification/#responseObject Response Object]}}
{{External|[https://swagger.io/docs/specification/2-0/describing-responses/ Describing Responses in OpenAPI 2.0]}}
 
A response is defined by its HTTP status code and the data returned in the [[#Response_Body|response body]] and/or [[#Response_Headers|headers]].
 
<syntaxhighlight lang='yaml'>
200:
  description: 200 response
   schema:
    $ref: '#/definitions/Empty'
    originalRef: '#/definitions/Empty'
  headers:
     Access-Control-Allow-Origin:
      type: 'string'
    Access-Control-Allow-Methods:
      type: 'string'
    Access-Control-Allow-Headers:
      type: 'string'
</syntaxhighlight>
 
====<tt>description</tt>====
 
The description is required. Represents a short description of the response.
 
==Response Body==
 
====<tt>schema</tt>====
 
The schema keyword is used to describe the response body. A schema may define:
* a primitive type such as "string" or "number", used for plain text responses. Note that Amazon API Gateway warns if it encounters a primitive type.
* an object
* an array – typically used with JSON and XML APIs
* a file
* a reference - the schema can be defined in-line or defined at the root level of the document and referenced via [[#.24ref|$ref]]. This is useful if multiple responses share the same schema.
 
For reference models (<code>RefModel</code>), <tt>model.setReference("RefName")</tt> puts the model in the correct state to refer to:
<syntaxhighlight lang='yaml'>
definitions:
  RefName:
     type: ...
</syntaxhighlight>
 
In-line schema:
<syntaxhighlight lang='yaml'>
responses:
  200:
    description: something
    schema:
      type: object
      properties:
        id:
          type: integer
          description: The user ID.
        username:
          type: string
          description: The user name.
</syntaxhighlight>
 
This is an example that uses references:
<syntaxhighlight lang='yaml'>
responses:
  200:
    description: something
    schema:
      $ref: '#/definitions/User'
...
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        description: The user ID.
      username:
        type: string
        description: The user name.
</syntaxhighlight>
 
"responseSchema" is sometimes used, but that seems to be deprecated.
 
===Empty Response Body===
 
For responses that have no body, like 204 No Content, no "schema" should be specified. This is conventionally treated as no-body response.
 
==Response Headers==
 
Responses can include custom headers, or headers that implement a protocol like [[#CORS|CORS]].
 
====<tt>headers</tt>====
 
The custom headers must be declared, under the "headers" section of the response. For OpenAPI 2.0, there is no way in Swagger to define common response headers for different response codes or different API operations. You need to define the headers for each response individually. "headers" is aA container that maps a header name to its definition. The header names are case insensitive. If a header is specified by the an extension, such as [[Amazon_API_Gateway_Extension_to_OpenAPI#x-amazon-apigateway-integration|x-amazon-apigateway-integration]], it has to be declared in the [[#headers|headers]] section for the corresponding response, otherwise a template error is generated.
 
<syntaxhighlight lang='yaml'>
200:
  description: 200 response
  ...
  headers:
    Access-Control-Allow-Origin:
      type: 'string'
    Access-Control-Allow-Methods:
      type: 'string'
    Access-Control-Allow-Headers:
      type: 'string'
  schema:
    $ref: '#/definitions/Empty'
    originalRef: '#/definitions/Empty'
</syntaxhighlight>
 
=Reference Object=
 
=$ref=
 
=CORS=
 
{{External|[https://swagger.io/docs/open-source-tools/swagger-ui/usage/cors/ CORS in Swagger]}}
 
More: {{Internal|Cross-Origin_Resource_Sharing|CORS}}
 
=Organizatorium=
 
==x-nullable==


Appears in automatically generated Swagger files, as such:
===Path===
For syntax of individual path specifications, see:


definitions:
{{Internal|OpenAPI Specification Path#Overview|OpenAPI Specification Path}}
    LibraryAccount:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          '''x-nullable''': '''true'''


  definitions:
==<tt>components</tt>==
   A:
{{External|https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject}}
     type: string
<font size=-2>
     title: A
  components:
    '''x-nullable''': '''true'''
   [[#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}}


When used for an API Gateway import, it errors out as:
==<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
|-
|}


Unable to create model for 'LibraryAccount': Invalid model specified: Validation Result: warnings : [], errors : [Invalid model schema specified. Unsupported keyword(s): ["x-nullable"]]
=<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

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

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoObject

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

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject
servers:
  - url: https://petstore.swagger.io/v2

paths

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject

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:

OpenAPI Specification Path

components

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject

components:
  schemas:
    Pet:
      [...]
    Error:
      [...]

schemas

The /components/schemas section of the OpenAPI specification defines reusable objects.

OpenAPI Specification Schemas

webhooks

A map of path item objects or reference objects.

security

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject

tags

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject

Data Types

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#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 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

$ref

OpenAPI Operation Declaration and Implementation Examples

OpenAPI Examples
Retrieved from "https://kb.novaordis.com/index.php?title=OpenAPI_Specification&oldid=107079"