openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: Example.com
  termsOfService: 'https://example.com/terms/'
  contact:
    email: contact@example.com
    url: 'http://example.com/contact'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  x-logo:
    url: 'https://www.openapis.org/wp-content/uploads/sites/3/2018/02/OpenAPI_Logo_Pantone-1.png'
  description: |
    This is an **example** API to demonstrate features of OpenAPI specification
externalDocs:
  description: Find out how to create Github repo for your OpenAPI spec.
  url: 'https://github.com/Rebilly/generator-openapi-repo'
servers:
  - url: 'http://example.com/api/v1'
  - url: 'https://example.com/api/v1'
tags:
  - name: Echo
    description: Example echo operations
  - name: User
    description: Operations about user
  - name: Introduction
    description: >
      This specification is intended to to be a good starting point for
      describing

      your API in [OpenAPI/Swagger
      format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).


      It also demonstrates features of
      [generator-openapi-repo](https://github.com/Rebilly/generator-openapi-repo)
      tool and [ReDoc](https://github.com/Rebilly/ReDoc) documentation engine.
      So beyond the standard OpenAPI syntax we use a few [vendor
      extensions](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md).
  - name: OpenAPI Specification
    description: >-
      The goal of The OpenAPI Specification is to define a standard,
      language-agnostic interface to REST APIs which allows both humans and
      computers to discover and understand the capabilities of the service
      without access to source code, documentation, or through network traffic
      inspection. When properly defined via OpenAPI, a consumer can understand
      and interact with the remote service with a minimal amount of
      implementation logic. Similar to what interfaces have done for lower-level
      programming, OpenAPI removes the guesswork in calling the service.
  - name: Markdown Description
    description: >-
      By using separate markdown documents and using `$ref` pointers to write
      the `description` field for individual `tags` in the root specification
      file, we can compose rich sections of text and arrange them in flexible
      ways. For exmaple...


      ```yaml

      tags:
        # 'Echo' and 'User' are the main paths in the spec
        - name: Echo
          description: Example echo operations
        - name: User
          description: Operations about user
        # Introduction includes some backround that I'd like to include
        # at the beginning of the docs
        - name: Introduction
          description:
            $ref: ./tags/introduction.md
        # This last section I'll include at the end in the appendix
        - name: Markdown Descriptions
          description:
            $ref: ./tags/markdown_desc.md
      # 'x-tagGroups' instructs redoc on how to arrange and order sections

      x-tagGroups:
        - name: Overview
          tags:
            - Introduction
        - name: Operations
          tags:
            - Echo
            - User
        - name: Appendix
          tags:
            - Markdown Descriptions
      ```


      `markdown_desc.md` includes headers and content in standard syntax, Which
      are inserted as markdown (and can be rendered as HTML) in the bundled
      spec:


      # Table Example


      | Tables   |      Are      |  Cool |

      |----------|:-------------:|------:|

      | col 1 is |  left-aligned | $1600 |

      | col 2 is |    centered   |   $12 |

      | col 3 is | right-aligned |    $1 |


      # Link Example


      Learn more about working with markdown in the [GitHub
      Guides](https://guides.github.com/features/mastering-markdown/).
x-tagGroups:
  - name: Overview
    tags:
      - Introduction
  - name: Operations
    tags:
      - Echo
      - User
  - name: Appendix
    tags:
      - OpenAPI Specification
      - Markdown Description
paths:
  '/users/{username}':
    parameters:
      - name: pretty_print
        in: query
        description: Pretty print response
        schema:
          type: boolean
    get:
      tags:
        - User
      summary: Get user by user name
      description: |
        Some description of the operation. 
        You can use `markdown` here.
      operationId: getUserByName
      parameters:
        - name: username
          in: path
          description: The name that needs to be fetched
          required: true
          schema:
            type: string
        - name: with_email
          in: query
          description: Filter users without email
          schema:
            type: boolean
      security:
        - main_auth:
            - 'read:users'
        - api_key: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                username: user1
                email: user@example.com
        '403':
          description: Forbidden
        '404':
          description: User not found
    put:
      tags:
        - User
      summary: Updated user
      description: This can only be done by the logged in user.
      operationId: updateUser
      parameters:
        - name: username
          in: path
          description: The name that needs to be updated
          required: true
          schema:
            type: string
      security:
        - main_auth:
            - 'write:users'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid user supplied
        '404':
          description: User not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
        description: Updated user object
        required: true
  /echo:
    post:
      tags:
        - Echo
      summary: Echo test
      description: Receive the exact message you've sent
      operationId: echo
      security:
        - api_key: []
        - basic_auth: []
      responses:
        '200':
          description: OK
          headers:
            X-Rate-Limit:
              description: calls per hour allowed by the user
              schema:
                type: integer
                format: int32
            X-Expires-After:
              $ref: '#/components/headers/ExpiresAfter'
          content:
            application/json:
              schema:
                type: string
              examples:
                response:
                  value: Hello world!
            application/xml:
              schema:
                type: string
            text/csv:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: Hello world!
          application/xml:
            schema:
              type: string
              example: Hello world!
        description: Echo payload
        required: true
components:
  headers:
    ExpiresAfter:
      description: date in UTC when token expires
      schema:
        type: string
        format: date-time
    Overview:
      description: |
        This is a file!
  schemas:
    Email:
      description: User email address
      type: string
      format: test
      example: john.smith@example.com
    User:
      type: object
      properties:
        username:
          description: User supplied username
          type: string
          minLength: 4
          example: John78
        firstName:
          description: User first name
          type: string
          minLength: 1
          example: John
        lastName:
          description: User last name
          type: string
          minLength: 1
          example: Smith
        email:
          $ref: '#/components/schemas/Email'
  securitySchemes:
    main_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'http://example.com/api/oauth/dialog'
          scopes:
            'read:users': read users info
            'write:users': modify or remove users
    api_key:
      type: apiKey
      in: header
      name: api_key
    basic_auth:
      type: http
      scheme: basic