openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
info:
  title: Sample API
  description: Optional multi-line or single-line description.
  version: 0.1.9
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional description.
      parameters:
        - description: "The name of user to query."
          in: query
          name: name
          schema:
            type: string
        - description: "The role of the user to query."
          in: query
          name: user
          schema:
            enum:
              - admin
              - regular
            type: string
      responses:
        '200':    # status code
          description: Successful response
          content:
            application/json:
              schema: 
                $ref: "#/components/schemas/UserList"
components:
  schemas:
    User:
      description: The metadata for a user.
      properties:
        id:
          description: The ID of the user.
          type: string
        name:
          description: The name of the user.
          type: string
      type: object
    UserList:
      description: A list of users.
      properties:
        users:
          description: The list of users. If nextPageToken is populated, then this list may be incomplete and an additional page of results should be fetched.
          items:
            $ref: "#/components/schemas/User"
          type: array
        incompleteSearch:
          description: Whether the search process was incomplete.
          type: boolean
        kind:
          default: 
          description: 'Identifies what kind of resource this is.'
          type: string
        nextPageToken:
          description: The page token for the next page of users.
          type: string
      type: object
     