Mơ thấy giáo viên dạy nhạc đang dạy bạn: Đây là một dấu hiệu tốt, cho thấy bạn đang trên con đường học hỏi và phát triển bản thân. HãyOpenAPI Specification (OAS) Definition Language Version 3.0
[TOC]
# Introduction
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via the OpenAPI Specification, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes the guesswork in calling a service.
# Specification
## Versions
The OpenAPI Specification is tracked via semantic versioning; therefore after version 3.0.0, only backwards compatible changes may be made.
## Format
A single OpenAPI Specification document MAY be represented in JSON or YAML format.
## File Extension
While there is no required file extension, the recommended extensions are `.json` for JSON documents and `.yaml` or `.yml` for YAML documents.
## OpenAPI Document Structure
The OpenAPI document MUST contain the following root properties:
– [`openapi`](#openapi)
– [`info`](#info)
– [`paths`](#paths)
The OpenAPI document MAY contain the following root properties:
– [`components`](#components)
– [`servers`](#servers)
– [`security`](#security)
– [`tags`](#tags)
– [`externalDocs`](#external-documentation-object)
The structure within the OpenAPI document is well defined and follows a fixed naming convention.
### Data Types
Primitive data types in the OpenAPI Specification are based on the types supported by the JSON Schema Specification Draft 4. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part.
Primitive Types:
| Type | Format | Comments |
| :—— | :——- | :—————————————————————————————————————————————————————————————————————————– |
| `string` | | |
| `integer` | `int32` | signed 32 bits |
| `integer` | `int64` | signed 64 bits |
| `number` | `float` | |
| `number` | `double` | |
| `boolean` | | |
| `array` | | Described in [`Arrays`](#fixed-fields-1) |
| `object` | | Described in [`Objects`](#fixed-fields-2) |
### Fixed Fields
#### Fixed Fields – 1
Field that MUST contain one value.
#### Fixed Fields – 2
Field that MUST contain zero or more values.
#### Free-Form Fields
Field that MAY contain zero or more values.
### Specification Extensions
The `OpenAPI Specification` allows the addition of properties to existing schema, either at the root level or within individual objects. This is achieved via the Specification Extensions. The extensions properties are always prefixed by `x-`. For example, `x-internal-id`.
The extensions may be used to supply additional information that does not fit into the standard schema. The values for Specification Extensions MAY be primitive, arrays or objects. There is no effect on the formal validation of the schema.
### Resolving References
Schemas that require the ability to reference other schemas MAY do so through the use of JSON Reference. The structure of a JSON Reference is that of a standard JSON object:
“`json
{ “$ref”: “[uri]” }
“`
The `uri` value MUST be a URI [RFC3986]. The `uri` MAY be relative or absolute, and MUST point to a location within the OpenAPI document.
### Relative Schema Document
Previously undiscovered properties are allowed, but their names MUST be prefixed with `”x-“`. The value may be a primitive, an array or an object.
## Schema
### OpenAPI Object
This is the root document object of the OpenAPI document.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :————————————————————————————————————————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| openapi | string | **REQUIRED**. This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API info.version string. | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a `url` value of `/`. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| paths | [Paths Object](#paths-object) | **REQUIRED**. The available paths and operations for the API. | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| components | [Components Object](#components-object) | An element to hold various schemas for use in the specification. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| tags | [[Tag Object](#tag-object)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the API.
| externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation.
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### Info Object
The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :———————————————————————————————————————————————————- | :——- | :——————————————————————— |
| title | string | **REQUIRED**. The title of the API. | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| description | string | A description of the API. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| termsOfService | string | A URL to the Terms of Service for the API. MUST be in the format of a URL. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| contact | [Contact Object](#contact-object) | The contact information for the exposed API. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| license | [License Object](#license-object) | The license information for the exposed API. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| version | string | **REQUIRED**. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### Contact Object
Contact information for the exposed API.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| name | string | The identifying name of the contact person/organization. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| url | string | The URL pointing to the contact information. MUST be in the format of a URL. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| email | string | The email address of the contact person/organization. MUST be in the format of an email address. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### License Object
License information for the exposed API.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| name | string | **REQUIRED**. The license name used for the API. | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| url | string | A URL to the license used for the API. MUST be in the format of a URL. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### Server Object
An object representing a Server.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :———————————————————————————————————————————————————- | :——- | :——————————————————————— |
| url | string | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{}`.
| description | string | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
| variables | [Map[string, Server Variable Object]](#server-variable-object) | A map between a variable name and its value. The values are used for substitution in the server’s URL.
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### Server Variable Object
An object representing a Server Variable for server URL substitution.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :———————————————————————————————————————————————————- | :——- | :——————————————————————— |
| enum | [string] | An enumeration of string values to be used if the substitution options are from a limited set.
| default | string | **REQUIRED**. The default value to use for substitution, and MUST be one the enum values if an enum is provided. | Yes | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| description | string | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### Components Object
Holds a set of reusable objects for different aspects of the OpenAPI Specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :———————————————————————————————————————————————————- | :——- | :——————————————————————— |
| schemas | [Map[string, Schema Object](#schema-object) OR [Reference Object](#reference-object)] | An object to hold reusable Schema Objects.
| responses | [Map[string, Response Object](#response-object) OR [Reference Object](#reference-object)] | An object to hold reusable Response Objects.
| parameters | [Map[string, Parameter Object](#parameter-object) OR [Reference Object](#reference-object)] | An object to hold reusable Parameter Objects.
| examples | [Map[string, Example Object](#example-object) OR [Reference Object](#reference-object)] | An object to hold reusable Example Objects.
| requestBodies | [Map[string, Request Body Object](#request-body-object) OR [Reference Object](#reference-object)] | An object to hold reusable Request Body Objects.
| headers | [Map[string, Header Object](#header-object) OR [Reference Object](#reference-object)] | An object to hold reusable Header Objects.
| securitySchemes | [Map[string, Security Scheme Object](#security-scheme-object) OR [Reference Object](#reference-object)] | An object to hold reusable Security Scheme Objects.
| links | [Map[string, Link Object](#link-object) OR [Reference Object](#reference-object)] | An object to hold reusable Link Objects.
| callbacks | [Map[string, Callback Object](#callback-object) OR [Reference Object](#reference-object)] | An object to hold reusable Callback Objects.
##### Patterned Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :——————————————————————————————————————————————————————————————————————- | :——- | :——————————————————————— |
| x- | any | Allows extensions to the OpenAPI Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. | No | [Specification Extensions](#specification-extensions) |
### Schema Object
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 4.
For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-04) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-04).
Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
The following properties are taken directly from the JSON Schema specification and follow the same specifications:
– title
– multipleOf
– maximum
– exclusiveMaximum
– minimum
– exclusiveMinimum
– maxLength
– minLength
– pattern
– maxItems
– minItems
– uniqueItems
– maxProperties
– minProperties
– required
– enum
The following properties are taken from the JSON Schema specification but their definitions have been extended by the OpenAPI Specification:
– type
– allOf
– properties
– additionalProperties
– description
– format
– items
The following properties are unique to the OpenAPI Specification:
– nullable
– discriminator
– readOnly
– writeOnly
– xml
– externalDocs
– example
– deprecated
#### Fixed Fields
| Field Name | Type | Description | Required | Specification |
| :——— | :—– | :————————————————————————————————————————————————————————————————————————————— | :——- | :——————————————————————— |
| nullable | boolean | Allows sending a `null` value for the defined schema. Default value is `false`. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| discriminator | [Discriminator Object](#discriminator-object) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See Composition and Inheritance for more details. | No | [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) |
| readOnly | boolean | Relevant only for Schema `
