Redocly response-contains-property guide

200.yaml

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: ../schemas/Email.yaml

201.yaml

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: ../schemas/Email.yaml

202.yaml

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: ../schemas/Email.yaml

path-item-with-examples.yaml

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.yaml
        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.yaml
      content:
        application/json:
          schema:
            $ref: ../components/responses/200.yaml
    '400':
      $ref: ../components/responses/Problem.yaml

path-item.yaml

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.yaml
    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.yaml
      content:
        application/json:
          schema:
            $ref: ../components/responses/200.yaml
    '400':
      $ref: ../components/responses/Problem.yaml

users_{username}.yaml

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/responses/200.yaml
          example:
            username: user1
            email: user@example.com
    '201':
      description: Created
      content:
        application/json:
          schema:
            $ref: ../components/responses/201.yaml
    '202':
      description: Accepted
      content:
        application/json:
          schema:
            $ref: ../components/responses/202.yaml
    '403':
      description: Forbidden
      $ref: ../components/responses/Problem.yaml
    '404':
      description: User not found
      $ref: ../components/responses/Problem.yaml
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.yaml
      application/xml:
        schema:
          $ref: ../components/schemas/User.yaml
    description: Updated user object
    required: true
  responses:
    '200':
      description: OK
    '400':
      description: Invalid user supplied
      $ref: ../components/responses/Problem.yaml
    '404':
      description: User not found
      $ref: ../components/responses/Problem.yaml