Why should I care about Swagger?

If you've worked with APIs before, you probably know how quickly things can get messy. Keeping track of endpoints, request parameters, and responses can become overwhelming—especially if you're new to API development.

Swagger is here to help by providing clear, visual, and interactive documentation for your APIs.

Let's dive into why it's useful and how easy it is to get started!

APIs without Swagger

Imagine you've created an API with several endpoints, each requiring specific parameters. Without Swagger, documenting and understanding your API usually means maintaining a manual document or spending lots of time explaining your API to new users or teammates:

GET /users/{user_id}
Parameters:
  - user_id: integer (required)
Response:
  - 200 OK: Returns user details in JSON format
  - 404 Not Found: User doesn't exist

POST /users
Parameters:
  - name: string
  - email: string
Response:
  - 201 Created: Successfully created user
  - 400 Bad Request: Missing or invalid parameters

This manual approach becomes a nightmare as your API grows or changes.

APIs with Swagger

Swagger solves this problem by clearly defining and visually representing your API structure. It also lets you test APIs directly through an interactive web interface.

Here's a brief YAML example of what your API documentation could look like using the OpenAPI specification:

openapi: 3.0.3
info:
  title: Sample Petstore API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: An array of pets

This YAML file is simple, readable, and best of all—Swagger automatically generates beautiful documentation:

• Interactive UI with clearly documented endpoints.
• Easily testable endpoints directly from your browser.

Swagger vs. OpenAPI: What's the difference?

Swagger was originally the name of both the specification and the suite of tools built around it. However, since version 3.0, the specification has been renamed "OpenAPI," and Swagger now primarily refers to the set of tools for working with the OpenAPI specification.

• Swagger: Refers to the tooling ecosystem (Swagger UI, Swagger Editor, SwaggerHub).
• OpenAPI: Refers specifically to the specification format (e.g., OpenAPI 3.0).

So, when someone mentions Swagger today, they usually mean the tooling around the OpenAPI specification.

Generating Swagger documentation from a YAML file

You can easily generate Swagger UI documentation from your YAML file using Swagger tools. Here's how:

1. Save your YAML file (e.g., api_spec.yaml).
2. Visit the Swagger Editor and upload your YAML file.
3. Instantly view interactive documentation and even host your documentation online using SwaggerHub.

Here's an example of what it will look like after rendering the above YAML file using the Swagger Editor.

Alternatively, use tools like swagger-ui locally:

npm install swagger-ui-dist

Then host it using a simple web server:

npx http-server path/to/swagger-ui-dist

How Swagger works with frameworks like FastAPI

One fantastic aspect of Swagger is its seamless integration with modern web frameworks such as FastAPI. FastAPI automatically generates Swagger documentation for you based on your code, without any additional configuration.

Here's how simple it is to document an API with FastAPI and Swagger:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id, "name": "Sam"}

@app.post("/users")
def create_user(name: str, email: str):
    return {"name": name, "email": email}

Just run your FastAPI app, and visit /docs. You’ll see an instantly generated Swagger UI!

Practical use-case

Imagine you're onboarding a new developer or sharing your API with a client. With Swagger, you simply send them a link, and they immediately have:

• A clear understanding of your API structure.
• Instant ability to test endpoints.
• Reduced confusion, back-and-forth, and documentation headaches.

This speeds up collaboration and reduces misunderstandings.

Conclusion

Swagger makes your API development life easier by providing automated, interactive documentation. It not only simplifies your API management but also greatly enhances clarity and ease of use.

Don't waste your time on manual documentation. Use Swagger and make your API user-friendly and maintainable!

Check out the official Swagger documentation for more information, and look at the OpenAPI specification for examples on that too.