Skip to content

Latest commit

 

History

History
315 lines (276 loc) · 7.02 KB

openapi-spec-swagger.md

File metadata and controls

315 lines (276 loc) · 7.02 KB
Raw

OpenAPI Specification / Swagger

Formerly known as Swagger RESTful API Documentation Specification.

Considerations:

Root Document

swagger: '2.0'
info:
  title: API Name
  version: '1.0.0'
  description: |
    Optional long description.
    May span multiple lines.
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /example-path/{example-query-param}:
    parameters: `Parameter Object`
      # Optional parameters that apply to entire path
      # Can be overridden within `Operation Object`, but cannot be removed
    get: `Operation Object`
    put: `Operation Object`
    post: `Operation Object`
    delete: `Operation Object`
    options: `Operation Object`
    head: `Operation Object`
    patch: `Operation Object`

###
# Tags
# Only useful to provide a description for tags used in `Operation Object`s.
###

tags:
  - name: TagName1
    description: Description
  - name: TagName2
    description: Description

###
# References
###

definitions:
  # Store `Schema Object` for re-use
  # Referenced elsewhere with `$ref: '#/definitions/ExampleObjectName'`
  ExampleObjectName1: `Schema Object`
parameters:
  # Store `Parameter Object` for re-use
  # Referenced elsewhere with `$ref: '#/parameters/example-param-name'`
  example-param-name-1: `Parameter Object`

###
# Security
###

securityDefinitions:
  uniqueName1: `Security Definitions Object`
  uniqueName2: `Security Definitions Object`
security: `Security Requirement Object`
  # Global security settings, individual `Operation Object` can override
  # Logical OR between multiple `Security Requirement Object`

Operation Object

parameters:
  - `Parameter Object`
  - `Parameter Object`
  - $ref: '#/parameters/example-param-name'
      # Reference to a `Parameter Object` stored in `parameters` in `Root Document`
responses:
  HTTP Status Code: `Response Object`
    # Common HTTP Status Codes: 200, 404
  default: `Response Object`
summary: Optional short summary. Less than 120 characters.
description: |
  Optional verbose description.
  Can span multiple lines.
tags:
  - OptionalTagName1
  - OptionalTagName2
security: `Security Requirement Object`
  # Logical OR between security requirements
  # Overrides `security` in `Root Document`

Parameter Object

name: exampleParameterName
in: query | header | path | formData | body
  # `query`: /example?eg
  # `path`: /example/{eg}
  # `body`: Request payload
    # Can only be *one* parameter per path marked as `body`
    # The `name` has no effect, and is usually kept as `body`
    # Requires `schema` property
description: Optional description
required: true
  # Optional, defaults to `false`
  # Unless `in` is `path`, then must be `true`
`Items Object`
  # type, format, etc (see `Items Object`)
schema: `Schema Object`
  # Only valid when `in` is `body`
allowEmptyValue: true
  # Optional, defaults to `false`
  # Only valid when `in` is `query` or `formData`

Response Object

description: Required description
schema: `Schema Object`
  # `type` may also be `file`
headers:
  # Optional
  example-header-name-1:
    - description: Optional description
      `Items Object`
examples:
  # Optional, example of the response message
  # Useful if the example generated by Swagger UI is misleading
  application/json:
    objectProperty1: objectValue
    objectProperty2:
      - arrayValue1
      - arrayValue2

Items Object

type: string | integer | number | boolean | array
format: date | date-time | unix-time | email | password | uuid | whatever-you-want
  # Optional
  # Note: value can be ANTHING!
  # More common formats: int32, int64, float, double, byte, binary, hostname, ipv4, ipv6, uri

###
# <type = array>
###
items: `Items Object`
collectionFormat: csv | ssv | tsv | pipes | multi
  # Optional
  # `csv`: `eg1, eg2` (default)
  # `ssv`: `eg1 eg2`
  # `tsv`: `eg1\teg2`
  # `pipes`: `eg1|eg2`
  # `multi`: `eg=eg1&eg=eg2`
    # Only valid when `in` is `query` or `formData`
###
# </type = array>
###

default: any
enum:
  - eg1
  - eg2
minimum: number
exclusiveMinimum: boolean
maximum: number
exclusiveMaximum: boolean
maxLength: integer
minLength: integer

Schema Object

`Items Object`
  # type, format, etc (see `Items Object`) 
  # IMPORTANT: `type` has an additional option: `object`
$ref: '#/definitions/ExampleObjectName1'
  # Optional
  # Reference to a `Schema Object` stored in `definitions` in `Root Document`
allOf:
  # Optional
  # A composition of multiple `Schema Object`s
  - $ref: '#/definitions/Example1'
  - $ref: '#/definitions/Example2'
  - `SchemaObject`

###
# <type = object>
###

properties:
  # Optional
  exampleProperty1: `Schema Object`
  exampleProperty2: `Schema Object`
additionalProperties: {}
  # Optional
  # Use if object is provided by client, and object is *not* allowed additional properties 
required:
  # Optional
  # Specify list of required properties within the object
  - exampleProperty1
  - exampleProperty2
###
# </type = object>
###

Security Definitions Object

1. Basic auth

type: basic
description: Optional description

2. API key

type: apiKey
description: Optional description
name: param-name
in: query | header

3. OAuth2

type: oauth2
description: Optional description
flow: implicit | password | application | accessCode
authorizationUrl: string
  # Required if `flow` is `implicit`, or `accessCode`
tokenUrl: string
  # Required if `flow` is `password`, `application`, or `accessCode`
scopes:
  example-scope-name-1: Description of scope
  example-scope-name-2: Description of scope

Security Requirement Object

security:
  # If security definition `type` is NOT `oauth2`, set to `[]`:
  - securityDefinitionUniqueName1: []
  - securityDefinitionUniqueName2: []
  # If security definition `type` is `oauth2`, provide list of scope names:
  - securityDefinitionUniqueName:
    - example-scope-name-1
    - example-scope-name-2

Examples

OAuth2 simple example

securityDefinitions:
  oauth:
    type: oauth2
    flow: implicit
    authorizationUrl: https://example.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token
    scopes:
      basic: Grants read access to all user data (granted by default)
security:
  - oauth:
    - basic

OAuth2 advanced example

securityDefinitions:
  oauth:
    type: oauth2
    flow: implicit``
    authorizationUrl: https://example.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token
    scopes:
      basic: Grants read access to all user data (granted by default)
      comments: Grants read/write access to comments
  key:
    type: apiKey
    in: query
    name: access_token
security:
  - oauth:
    - basic
    - comments
  - key: []