web_deploy.yaml

openapi: 3.1.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://redocly.github.io/openapi-template/logo.png
  description: |
    This is an **example** API to demonstrate features of the OpenAPI specification.

    # Introduction

    This API definition 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/3.0.2.md).

    It also demonstrates features of the
    [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool
    and 

    the [Redoc](https://github.com/Redocly/Redoc) documentation engine. Beyond
    the standard OpenAPI syntax, we use a few 

    [vendor
    extensions](https://github.com/Redocly/Redoc/blob/master/docs/redoc-vendor-extensions.md).


    # OpenAPI Specification

    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.
tags:
  - name: Echo
    description: Example echo operations.
  - name: User
    description: Operations about users.
  - name: Tag
    description: This is a tag description.
servers:
  - url: https://{tenant}/api/v1
    variables:
      tenant:
        default: www
        description: Your tenant id
  - url: https://example.com/api/v1
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
          $ref: '#/components/responses/Problem'
        '404':
          description: User not found
          $ref: '#/components/responses/Problem'
    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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
        description: Updated user object
        required: true
      responses:
        '200':
          description: OK
        '400':
          description: Invalid user supplied
          $ref: '#/components/responses/Problem'
        '404':
          description: User not found
          $ref: '#/components/responses/Problem'
  /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
        '400':
          description: Unauthorized
      requestBody:
        content:
          application/json:
            schema:
              type: string
              example: Hello world!
          application/xml:
            schema:
              type: string
              example: Hello world!
        description: Echo payload
        required: true
      x-codeSamples:
        - lang: C#
          source: |
            API.v1.Echo echo = new API.v1.Echo();
            echo.message = "Hello World!");
            EchoResponse response = echo.post();
            if (response.statusCode == HttpStatusCode.Created)
            {
              // Success
            }
            else
            {
              // Something wrong -- check response for errors
              Console.WriteLine(response.getRawResponse());
            }
        - lang: PHP
          source: |
            $form = new \API\Entities\Echo();
            $form->setMessage("Hello World!");
            try {
                $pet = $client->echo()->post($form);
            } catch (UnprocessableEntityException $e) {
                var_dump($e->getErrors());
            }
  /pathItem:
    post:
      tags:
        - Tag
      summary: Operation summary
      description: |
        Operation description **Markdown**.
      operationId: operationId
      security:
        - api_key: []
        - basic_auth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schema'
        description: requestBody description
        required: true
      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:
                $ref: '#/components/schemas/Schema'
        '400':
          $ref: '#/components/responses/Problem'
  /pathItemWithExamples:
    post:
      tags:
        - Tag
      summary: Operation summary with examples
      description: |
        Operation description **markdown**.
      operationId: postPathItemWithExamples
      security:
        - api_key: []
        - basic_auth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schema'
            examples:
              mapName:
                summary: My first example
                description: My first example's description.
                value:
                  stringProperty: tada
              mapNameDoesNotShowInDocsUnlessSummaryIsNotProvided:
                value:
                  stringProperty: checkmark
        description: requestBody description
        required: true
      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:
                $ref: '#/components/schemas/Schema'
        '400':
          $ref: '#/components/responses/Problem'
components:
  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
  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'
    Problem:
      type: object
      additionalProperties: true
      minProperties: 1
      description: The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)].
      properties:
        type:
          type: string
          description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the problem type. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
          format: uri
        title:
          type: string
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
        status:
          type: integer
          description: The HTTP status code.
          minimum: 400
          maximum: 599
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
    Schema:
      type: object
      title: Scalars
      properties:
        stringProperty:
          description: Property name's description (type is string)
          type: string
          examples:
            - example
            - sample
        readOnlyStringProperty:
          description: Notice this only appears in the response.
          type: string
          readOnly: true
          examples:
            - example
        writeOnlyStringProperty:
          description: Notice this only appears in the request.
          type: string
          writeOnly: true
          examples:
            - example
        minLengthString:
          description: Property name's description (type is string)
          type: string
          minLength: 4
          examples:
            - example
        maxLengthString:
          description: Property name's description (type is string)
          type: string
          maxLength: 140
          examples:
            - example
        minAndMaxLengthString:
          description: Property name's description (type is string)
          type: string
          minLength: 4
          maxLength: 140
          examples:
            - example
        nullableOrStringProperty:
          description: Property name's description (type is string or null)
          type:
            - string
            - 'null'
          examples:
            - example
        stringEnumValues:
          description: Property name's description (type is string)
          type: string
          enum:
            - sample
            - example
            - specimen
            - case
            - instance
            - illustration
        stringDateTime:
          description: Property name's description (type is string, format is date-time)
          type: string
          format: date-time
        stringDate:
          description: Property name's description (type is string, format is date-time)
          type: string
          format: date
        stringEmail:
          description: Property name's description (type is string, format is email)
          type: string
          format: email
        stringIpAddressV4:
          description: Property name's description (type is string, format is ipv4 address)
          type: string
          format: ipv4
        stringIpAddressV6:
          description: Property name's description (type is string, format is ipv6 address)
          type: string
          format: ipv6
        stringPassword:
          description: Property name's description (type is string, format is password)
          type: string
          format: password
        stringHostname:
          description: Property name's description (type is string, format is hostname)
          type: string
          format: hostname
        stringUri:
          description: Property name's description (type is string, format is uri)
          type: string
          format: uri
        stringUuid:
          description: Property name's description (type is string, format is uuid)
          type: string
          format: uuid
        numberProperty:
          description: Property name's description (type is number)
          type: number
          example: 8
        numberFloat:
          description: Property name's description (type is number, format is float)
          type: number
          format: float
        numberDouble:
          description: Property name's description (type is number, format is double)
          type: number
          format: double
        numberGreaterThanOrEquals:
          description: Property name's description (type is number)
          type: number
          minimum: 5
        numberGreaterThan:
          description: Property name's description (type is number)
          type: number
          exclusiveMinimum: 5
        numberLessThan:
          description: Property name's description (type is number)
          type: number
          exclusiveMaximum: 8
        numberLessThanOrEquals:
          description: Property name's description (type is number)
          type: number
          maximum: 8
        numberRange:
          description: Property name's description (type is number)
          type: number
          minimum: 5
          maximum: 8
        numberRangeExclusiveMaximum:
          description: Property name's description (type is number)
          type: number
          minimum: 5
          exclusiveMaximum: 8
        numberRangeExclusiveMinimumAndMaximum:
          description: Property name's description (type is number)
          type: number
          exclusiveMinimum: 5
          exclusiveMaximum: 8
        numberMultipleOf:
          description: Property name's description (type is number)
          type: number
          multipleOf: 2
        integerType:
          description: Property name's description (type is integer)
          type: integer
        integer32bit:
          description: Property name's description (type is integer, format is int32)
          type: integer
          format: int32
        integer64bit:
          description: Property name's description (type is integer, format is int64)
          type: integer
          format: int64
        booleanProperty:
          description: Property name's description (type is boolean)
          type: boolean
  responses:
    Problem:
      description: Problem
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  headers:
    ExpiresAfter:
      description: date in UTC when token expires
      schema:
        type: string
        format: date-time