api.yaml

openapi: "3.0.1"
info:
  title: Movies API
  version: v1

paths:
  /movies:
    summary: A set of movies
    get:
      summary: Get a list of movies
      responses:
        '200':
          description: Movie list response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Movie'
      security: 
        - OAuth2:
          - read
    post:
      summary: Add a new movie to the set
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Movie'
      responses:
        '201':
          description: Returns the new movie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewMovie'
      security: 
        - OAuth2:
          - write

  /movies/{id}:
    summary: Details of a movie
    get:
      summary: Get a specific movie
      responses:
        '200':
          description: Movie detail response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
      security: 
        - OAuth2:
          - read
    put:
      summary: Update a specific movie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMovie'
      responses:
        '200':
          description: Returns the updated movie
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
      security: 
        - OAuth2:
          - write
    delete:
      summary: Delete a specific movie
      responses:
        '204':
          description: Confirms the movie deletion
      security: 
        - OAuth2:
          - write
      
components:
  schemas:
    Movie:
      allOf:
        - $ref: '#/components/schemas/NewMovie'
        - required:
          - id
          properties:
            id:
              type: string
    NewMovie:
      properties:
        title:
          type: string
        description:
          type: string
      required:
        - title

  securitySchemes:
    OAuth2:
      type: oauth2
      flows: 
        password:
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access