OpenAPI Specification

https://spec.openapis.org/oas/v3.0.3
Admin
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface...
Tokens:42,295
Snippets:256
Trust Score:9.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Paths Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Paths Object in YAML format, showing a GET operation for /pets that returns a list of pets.

```yaml
/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'
```

--------------------------------

### Path Item Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML representation of the same Path Item Object example, showing the GET operation and parameters in YAML syntax.

```yaml
get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string 
  style: simple
```

--------------------------------

### Media Type Examples (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the Media Type Object example, showing schema reference and named examples (cat, dog, frog) with inline values and a $ref.

```yaml
application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"
```

--------------------------------

### Model with Example YAML

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the model with example, defining 'id' and 'name' properties, requiring 'name', and providing an example.

```YAML
type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Puma
  id: 1
```

--------------------------------

### Example Object in a Parameter

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to reference an example in a parameter using the $ref keyword. The example is defined in the components/examples section.

```yaml
parameters:
  - name: 'zipCode'
    in: 'query'
    schema:
      type: 'string'
      format: 'zip-code'
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'
```

--------------------------------

### Paths Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Paths Object in JSON format, showing a GET operation for /pets that returns a list of pets.

```json
{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {         
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example Object in a Response

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to reference an example in a response's content. The example is defined in the components/examples section.

```yaml
responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'
```

--------------------------------

### Media Type Examples (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Media Type Object in JSON showing schema reference and multiple examples (cat, dog, frog) with inline values and a $ref.

```json
{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}
```

--------------------------------

### Example Object in a Request Body

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to define examples for different media types in a request body. The 'application/json' example uses inline values, while 'application/xml' and 'text/plain' use externalValue URLs.

```yaml
requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}
    'application/xml':
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: 'http://example.org/examples/address-example.xml'
    'text/plain':
      examples:
        textExample:
          summary: This is a text example
          externalValue: 'http://foo.bar/examples/address-example.txt'
```

--------------------------------

### Single server example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Describes a single server with a URL and description in JSON format.

```json
{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}
```

--------------------------------

### Single server example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Describes a single server with a URL and description in YAML format.

```yaml
url: https://development.gigantic-server.com/v1
description: Development server
```

--------------------------------

### External Documentation Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML representation of the same External Documentation Object example.

```yaml
description: Find more info here
url: https://example.com
```

--------------------------------

### Reference Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Reference Object using $ref to reference a component, in YAML.

```yaml
$ref: '#/components/schemas/Pet'
```

--------------------------------

### Tag Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Tag Object with name and description fields, in YAML.

```yaml
name: pet
description: Pets operations
```

--------------------------------

### Tag Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Tag Object with name and description fields, in JSON.

```json
{
	"name": "pet",
	"description": "Pets operations"
}
```

--------------------------------

### Info Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML representation of the Info Object with the same fields as the JSON example.

```yaml
title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
```

--------------------------------

### Reference Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Reference Object using $ref to reference a component, in JSON.

```json
{
	"$ref": "#/components/schemas/Pet"
}
```

--------------------------------

### Path Item Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

JSON representation of a Path Item Object with a GET operation and a path parameter. The example shows a response with a schema referencing '#/components/schemas/Pet' and an error response referencing '#/components/schemas/ErrorModel'.

```json
{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}
```

--------------------------------

### License Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML representation of the License Object with the same fields as the JSON example.

```yaml
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
```

--------------------------------

### Responses Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the Responses Object example, with '200' quoted for compatibility and default response for errors.

```yaml
'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'
```

--------------------------------

### Contact Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML representation of the Contact Object with the same fields as the JSON example.

```yaml
name: API Support
url: http://www.example.com/support
email: support@example.com
```

--------------------------------

### Relative Schema Document Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Reference Object referencing a relative schema document, in JSON.

```json
{
  "$ref": "Pet.json"
}
```

--------------------------------

### OAuth Flow Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the OAuth2 security scheme example, using the same implicit and authorizationCode flows.

```yaml
type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
```

--------------------------------

### Model with Example JSON

Source: https://spec.openapis.org/oas/v3.0.3.html

Defines an object schema with 'id' and 'name' properties, requiring 'name', and includes an example instance with name 'Puma' and id 1.

```JSON
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "Puma",
    "id": 1
  }
}
```

--------------------------------

### License Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

JSON representation of the License Object with name and URL fields.

```json
{
  "name": "Apache 2.0",
  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}
```

--------------------------------

### Path parameter of string value (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the path parameter example.

```yaml
name: username
in: path
description: username to fetch
required: true
schema:
  type: string
```

--------------------------------

### Header Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

A simple header of type integer, shown in YAML format.

```yaml
description: The number of allowed requests in the current period
schema:
  type: integer
```

--------------------------------

### Header Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

A simple header of type integer, shown in JSON format.

```json
{
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}
```

--------------------------------

### Complex parameter using content (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the complex parameter example using 'content'.

```yaml
in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number
```

--------------------------------

### Models with Composition YAML

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the composition example, defining ErrorModel and ExtendedErrorModel using allOf.

```YAML
components:
  schemas:
    ErrorModel:
      type: object
      required:
      - message
      - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
      - $ref: '#/components/schemas/ErrorModel'
      - type: object
        required:
        - rootCause
        properties:
          rootCause:
            type: string
```

--------------------------------

### Multiple servers example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to define multiple servers in the OpenAPI Object's 'servers' field using JSON.

```json
{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}
```

--------------------------------

### Multiple servers example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to define multiple servers in the OpenAPI Object's 'servers' field using YAML.

```yaml
servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server
```

--------------------------------

### Header parameter with array of int64 (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the header parameter example with 'style: simple'.

```yaml
name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple
```

--------------------------------

### Components Object Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML representation of the same Components Object example, providing an alternative format for defining reusable components. This example is from section 4.7.7.2 of the OpenAPI Specification v3.0.3.

```yaml
components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets
```

--------------------------------

### Server variables example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to use server variables in a server URL template, including default values and an enum for the port variable, with comments explaining open values.

```yaml
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2
```

--------------------------------

### Components Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

JSON representation of the Components Object example, defining reusable schemas, parameters, responses, and security schemes. This example is from section 4.7.7.2 of the OpenAPI Specification v3.0.3.

```json
"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Info Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

JSON representation of the Info Object with title, description, terms of service, contact, license, and version fields.

```json
{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.example.com/support",
    "email": "support@example.com"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}
```

--------------------------------

### Server variables example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows how to use server variables in a server URL template, including default values and an enum for the port variable.

```json
{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}
```

--------------------------------

### Responses Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows a 200 response for a successful operation and a default response for errors, using $ref to Pet and ErrorModel schemas.

```json
{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}
```

--------------------------------

### Relative Schema Document Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Reference Object referencing a relative schema document, in YAML.

```yaml
$ref: Pet.yaml
```

--------------------------------

### External Documentation Object Example

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of an External Documentation Object that references an external resource for extended documentation.

```APIDOC
## External Documentation Object Example

### Description
Allows referencing an external resource for extended documentation.

### Fields
- **description** (string) - Optional - A short description of the target documentation.
- **url** (string) - Required - The URL for the target documentation.

### Example
```json
{
  "description": "Find more info here",
  "url": "https://example.com"
}
```
```

--------------------------------

### Relative Documents With Embedded Schema Example (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Reference Object referencing a relative document with an embedded schema, in YAML.

```yaml
$ref: definitions.yaml#/Pet
```

--------------------------------

### Relative Documents With Embedded Schema Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

Example of a Reference Object referencing a relative document with an embedded schema, in JSON.

```json
{
  "$ref": "definitions.json#/Pet"
}
```

--------------------------------

### Optional query parameter with array of strings (YAML)

Source: https://spec.openapis.org/oas/v3.0.3.html

YAML equivalent of the optional query parameter example.

```yaml
name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true
```

--------------------------------

### XML attribute, prefix and namespace example

Source: https://spec.openapis.org/oas/v3.0.3.html

Shows a full model definition with XML attribute, namespace, and prefix. The 'id' property becomes an XML attribute, and the 'name' property uses a namespace and prefix.

```json
{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "http://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}
```

```yaml
Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: http://example.com/schema/sample
        prefix: sample
```

```xml
<Person id="123">
    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
</Person>
```

--------------------------------

### OAuth Flow Object Example (JSON)

Source: https://spec.openapis.org/oas/v3.0.3.html

JSON example of an OAuth2 security scheme with implicit and authorizationCode flows. Shows required authorizationUrl and tokenUrl fields and scopes map.

```json
{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}
```
Tokens:
Raw