OpenAPI Specification for CS 493 Example API

openapi.yaml

openapi: 3.0.1
info:
  version: 1.0.0
  title: Book-a-Place API
  description: A simple API for an Airbnb-like application.
  
paths:
  /lodgings:
    get:
      summary: Fetch a list of lodgings
      description: >
        Returns a paginated list of lodgings.
      operationId: getLodgings
      tags:
        - lodgings
      parameters:
        - name: page
          in: query
          description: >
            Specifies a specific page of lodgings to request.
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageNumber:
                    type: integer
                    description: Page number of returned lodgings.
                    example: 1
                  totalPages:
                    type: integer
                    description: Total number of pages available.
                    example: 127
                  pageSize:
                    type: integer
                    description: Number of lodgings per page.
                    example: 10
                  totalCount:
                    type: integer
                    description: Total number of lodgings.
                    example: 1264
                  lodgings:
                    type: array
                    description: The returned lodgings.
                    items:
                      $ref: '#/components/schemas/Lodging'
                      
    post:
      summary: Add a new lodging
      description: >
        Creates a new lodging with specified data and adds it to the application's database.
      operationId: addNewLodging
      tags:
        - lodgings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Lodging'
      responses:
        201:
          description: New lodging successfully added
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Unique ID of the created lodging.
                    example: 12345
        400:
          description: Incorrectly-formatted request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /lodgings/{lodgingID}:
    parameters:
      - name: lodgingID
        in: path
        description: Unique ID of a lodging.
        schema:
          type: integer
        example: 12345
        required: true
        
    get:
      summary: Fetch data for a specific lodging.
      description: >
        Returns complete data for a the lodging specified by `lodgingID`.
      operationId: getLodging
      tags:
        - lodgings
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lodging'
        404:
          description: Specified `lodgingID` not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
    put:
      summary: Update data for a specific lodging.
      description: >
        Replaces the data for the lodging specified by `lodgingID`.
      operationId: replaceLodging
      tags:
        - lodgings
      requestBody:
        description: >
          Lodging data to replace data for the lodging specified by `lodgingID`.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Lodging'
      responses:
        200:
          description: Success
        400:
          description: Incorrectly-formatted request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Specified `lodgingID` not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
    delete:
      summary: Remove a specific lodging from the database.
      description: >
        Completely removes the data for the lodging specified by `lodgingID`.
      operationId: removeLodging
      tags:
        - lodgings
      responses:
        204:
          description: Success
        404:
          description: Specified `lodgingID` not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Lodging:
      description: >
        An object representing information about a single lodging.
      type: object
      properties:
        name:
          type: string
          description: Name of the lodging.
          example: My Cool Condo
        description:
          type: string
          description: Textual description of the lodging.
          example: This is a nice place to stay, right downtown and near the river.
        price:
          type: number
          description: Price of the lodging, per night, in USD.
          example: 128.00
          minimum: 0.01
      required:
        - name
        - price
  
    Error:
      description: >
        An object representing an error response from the API.
      type: object
      properties:
        err:
          type: string
          description: A message describing the error.
          
tags:
  - name: lodgings
    description: >
      API endpoints related to lodgings resources