openapi_full_example.yaml

openapi: '3.0.3'
info:
  title: 'Book Library'
  description: 'A catalog of books for a public library'
  version: '1.0'
servers:
  - url: http://localhost:8080/

components:
  schemas:
    Book:
      # Definition of a "Book" object
      type: object
      properties:
        id:
          type: integer
          minimum: 0
        title:
          type: string
        year:
          type: integer
          minimum: 1400
          maximum: 2021
        author:
          type: string
        pages:
          type: integer
        typeOfBook:
          type: string
          enum:
            - "novel"
            - "encyclopedia"
            - "comic"
            - "biography"
            - "history"
      required:
        - "title"
        - "author"
      example:
        title: "El Quijote"
        author: "Miguel de Cervantes"
        year: 1605
        pages: 750
        typeOfBook: "novel"

  securitySchemes:
    auth:
      # Authentication with an API key sent as a query string
      type: apiKey
      name: api_key
      description: API key provided by the administrator, in order to be able to add new books or modify the existing ones
      in: query

paths:
  /books:
    get:
      # GET /books
      description: 'Return all the books available in the library'
      responses:
        '200':
          description: 'List with all the available books in the library'
          content:
            'application/json':
              schema:
                # Returns an array of "Book" elements
                type: array
                items:
                  $ref: '#/components/schemas/Book'

    post:
      # POST /books
      description: 'Add a new book to the library'
      security:
        # This operation needs the client to be authenticated
        - auth: []      
      requestBody:
        description: Details of the book to add
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: 'Book successfully added to the library'      
        '401':
          description: 'Non authorized to do this operation'  
        '400':
          description: 'Bad request'

  /books/search:
    get:
      # GET /books/search
      description: 'Get all the books matching your search criteria'
      parameters:
        - name: title
          in: query
          description: 'Book title'
          schema:
            type: string     
        - name: year
          in: query
          description: 'Publication year'
          schema:
            type: integer 
        - name: author
          in: query
          description: 'Book author'
          schema:
            type: string       
        - name: typeOfBook
          in: query
          description: 'Type of book'
          schema:
            type: string
            
      responses:
        '200':
          description: 'List with all the books matching the search criteria'
          content:
            'application/json':
              schema:
                # Returns an array of "Book" elements
                type: array
                items:
                  $ref: '#/components/schemas/Book'                       

  /books/{id}:
    get:
      # GET /books/{id}
      description: 'Return the details about the book with the requested ID'
      parameters:
        - name: id
          in: path
          description: 'ID of the book to request'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'The requested book'
          content:
            'application/json':
              schema:
                # Returns the requested book
                $ref: '#/components/schemas/Book'
        '404':
          description: 'Book with the requested ID not found'

    put:
      # PUT /books/{id}
      description: 'Update the details about the book with the specified ID'
      security:
        - auth: []
      parameters:
        - name: id
          in: path
          description: 'ID of the book to modify'
          required: true
          schema:
            type: string
      requestBody:
        description: New details of the book to be modified
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Book'    
      responses:
        '200':
          description: 'Book successfully updated'
        '404':
          description: 'Book with the requested ID not found'
 
    delete:
      # DELETE /books/{id}
      description: 'Delete the book with the specified ID'  
      security:
        - auth: []
      parameters:
        - name: id
          in: path
          description: 'ID of the book to delete'
          required: true
          schema:
            type: string       
      responses:
        '201':
          description: 'Book successfully removed'         
        '404':
          description: 'Book with the requested ID not found'