OpenAPI Specification (Swagger) in Rest API - Mini Project: Build & Apply

Create a Simple OpenAPI Specification (Swagger)

📖 Scenario: You are building a simple API for a bookstore. You want to describe your API clearly so other developers can understand how to use it. OpenAPI Specification (Swagger) helps you write this description in a standard way.

🎯 Goal: Create a basic OpenAPI Specification file that describes a bookstore API with one endpoint to get a list of books.

📋 What You'll Learn

Create the main OpenAPI info section with title and version

Define the server URL where the API is hosted

Add a path for /books with a GET method

Describe the response for the GET method with status 200 and a JSON content type

💡 Why This Matters

🌍 Real World

OpenAPI Specification is used to describe REST APIs clearly so developers can understand and use them easily.

💼 Career

Knowing how to write and read OpenAPI specs is important for backend developers, API designers, and technical writers.

1

Set up the basic OpenAPI info

Create a variable called openapi_spec and assign it a dictionary with the keys "openapi" set to "3.0.0", and "info" which is another dictionary containing "title" set to "Bookstore API" and "version" set to "1.0.0".

Rest API

# Your code here

Need a hint?

Use nested dictionaries to create the info section inside openapi_spec.

2

Add the server URL

Add a key "servers" to the openapi_spec dictionary. Set it to a list with one dictionary inside that has the key "url" set to "https://api.bookstore.com".

Rest API

openapi_spec = {
    "openapi": "3.0.0",
    "info": {
        "title": "Bookstore API",
        "version": "1.0.0"
    }
}
# Your code here

Need a hint?

The servers key holds a list of server objects. Each server object has a url.

3

Add the /books GET endpoint

Add a key "paths" to openapi_spec. It should be a dictionary with a key "/books". This key maps to another dictionary with a key "get". The "get" dictionary should have a key "responses" which is a dictionary with a key "200". The "200" key maps to a dictionary with a key "description" set to "A list of books" and a key "content" which is a dictionary with a key "application/json" that maps to an empty dictionary.

Rest API

openapi_spec = {
    "openapi": "3.0.0",
    "info": {
        "title": "Bookstore API",
        "version": "1.0.0"
    },
    "servers": [
        {"url": "https://api.bookstore.com"}
    ]
}
# Your code here

Need a hint?

Use nested dictionaries to describe the path, method, and response structure.

4

Print the OpenAPI Specification

Write a print statement to display the openapi_spec dictionary.

Rest API

openapi_spec = {
    "openapi": "3.0.0",
    "info": {
        "title": "Bookstore API",
        "version": "1.0.0"
    },
    "servers": [
        {"url": "https://api.bookstore.com"}
    ],
    "paths": {
        "/books": {
            "get": {
                "responses": {
                    "200": {
                        "description": "A list of books",
                        "content": {
                            "application/json": {}
                        }
                    }
                }
            }
        }
    }
}
# Your code here

Need a hint?

Use print(openapi_spec) to show the whole specification.