openapi: 3.0.0
servers:
  - url: https://mycoolapi.name
info:
  title: Notes API
  version: '1'
paths:
  /notes/{id}:
    get:
      summary: Retrieve a note by ID
      tags:
        - notes
      parameters:
        - name: id
          in: path
          schema:
            type: number
          required: true
      responses:
        200:
          description: A note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
  /notes:
    get:
      summary: Retrieve all notes
      tags:
        - notes
      parameters:
        - name: title
          description: Filter by title
          in: query
          schema:
            type: string
            maxLength: 100
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/offsetParam'
      responses:
        200:
          description: A list of note resources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Note'
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
    post:
      summary: Add a new note
      tags:
        - notes
      security:
        - OAuth2: ['note:write']
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Note'
      responses:
        201:
          description: 'Note created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        422:
          description: 'Invalid note'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://mycoolapi.name/oauth/authorize
          tokenUrl: https://mycoolapi.name/oauth/token
          scopes:
            'note:read': Read notes
            'note:write': Write notes
    BearerAuth:
      type: http
      scheme: bearer
  headers:
    X-Total-Count:
      schema:
        type: integer
        description: Total number of records
        example: 100
  parameters:
    limitParam:
      name: limit
      description: 'Max records to return'
      in: 'query'
      schema:
        type: number
    offsetParam:
      name: offset
      description: 'How many records to skip'
      in: 'query'
      schema:
        type: number
  schemas:
    Note:
      type: 'object'
      required:
      - 'title'
      - 'body'
      properties:
        id:
          type: 'number'
          format: 'int64'
          readOnly: true
        title:
          type: 'string'
          example: 'A very important note'
          maxLength: 100
        body:
          type: 'string'
        created_at:
          type: 'string'
          format: 'date-time'
          readOnly: true
    ValidationError:
      type: array
      items:
        $ref: '#/components/schemas/FieldValidationError'
    FieldValidationError:
      type: object
      required:
        - message
        - key
      properties:
        key:
          type: string
          example: title
        message:
          type: string
          example: Must be <= 100 characters