In the first part of this blog series, I included the below code. In this part, we will be discussing how to write one such file by explaining what each keyword signifies.

openapi: 3.0.0

info:
  version: 0.0.1
  title: Library Service
  description:
    This is a sample description

servers:
  - url: https://localhost:8080

tags:

  - name: "Books"
    description: This is an API for Books
  - name: "Users"
    description: This is an API for Users

paths:

  /books/{bookId}:
    parameters:
      - name: bookId
        description: Id of the book
        schema:
          type: string
        in: path   
        required: true

    get:
      summary: Get a book by book Id
      operationId: getBookById
      tags:
        - "Books"
      responses:
        '200':
          description: SUCCESSFUL OPERATION
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Book'

  /books:

    post:
      summary: Creates a book
      description: This API creates a book
      tags:
        - "Books"
      operationId: createBook
      requestBody:
        description: Inputs for creating a book
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                type: string

    get:
      summary: Get all books
      description: This API gets all of the books
      tags:   
        - "Books"
      operationId: getAllBooksInLibrary          
      responses:
        '200':
          description: SUCCESSFUL OPERATION
          content:    
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
        '400':
          description: BAD REQUEST
        '401':
          description: UNAUTHORIZED

components:
  schemas:

    Book:
      description: This is a book object
      type: object
      required:
        - name
      properties:
        name:
          description: This is the name of the book
          type: string
        author:
          description: This is the author of the book
          type: string

Explanation

1. openapi: 3.0.0: This specifies the version of the OpenAPI Specification being used.

2. info: Contains metadata about your API.

   • version: The version of the API.

   • title: The title or name of the API.

   • description: A brief description of the API.

3. servers: Specifies the server(s) where your API can be accessed. In this case, it's set to https://localhost:8080.

4. tags: Provides tags for grouping and categorizing your API endpoints.

   • You have two tags here: "Books" and "Users," each with a description.

5. paths: Defines the API endpoints and their associated operations (GET, POST, etc.).

   • /books/{bookId}: This defines a path parameter {bookId} for getting a specific book by its ID.

     • parameters: Describes the parameters for this endpoint, including bookId.

     • get: Describes the HTTP GET operation for retrieving a book by ID.

       • summary: A brief summary of the operation.

       • operationId: A unique identifier for the operation.

       • tags: Specifies the tags to which this operation belongs.

       • responses: Describes possible responses, such as '200' for a successful response.

         • content: Defines the response content type and schema.

   • /books: This defines the path for managing books.

     • post: Describes the HTTP POST operation for creating a book.

       • summary: A brief summary of the operation.

       • description: A more detailed description.

       • requestBody: Specifies the request body content type and schema.

       • responses: Describes possible responses, such as '201' for a successful creation.

     • get: Describes the HTTP GET operation for retrieving all books.

       • summary: A brief summary.

       • description: A more detailed description.

       • responses: Describes possible responses, including '200' for a successful response.

6. components: Contains reusable components, such as data schemas.

   • schemas: Defines the data schema for the "Book" object.

     • description: A description of the schema.

     • type: Specifies the type of the schema, which is an object.

     • required: Lists required properties.

     • properties: Defines the properties of the "Book" object, including "name" and "author."

Swagger Editor

Head over to https://editor.swagger.io and you will find some default Petstore code. I highly recommend you look at the code, and understand what the new keywords you are looking at mean. And observe how your changes get reflected in the right side panel.

Now, paste the above Library YAML code into the editor and see the changes on the right panel.

Now as an additional task, practice writing your API for a college service. This should include get, post, put and delete with as many additional things as you can add.