Chronicles of the Empire: Introduction to API Documentation

Salve, chronicler of the Empire! Welcome to one of the most important missions of our Empire - creating the API Chronicles. Just as the ancient Romans meticulously documented their laws, imperial decrees, and legion organization in the Annals of the Empire, we will document our API using Swagger and OpenAPI.

What is OpenAPI?

OpenAPI (formerly known as Swagger Specification) is a standard specification for describing REST API interfaces. Think of it as the official administrative language of the Empire - a unified way of communication between provinces.

The OpenAPI specification defines the API structure in JSON or YAML format:

1// This is what an endpoint description looks like in OpenAPI format
2{
3  "paths": {
4    "/legiones": {
5      "get": {
6        "summary": "Get list of legions",
7        "description": "Returns all legions of the Empire",
8        "responses": {
9          "200": {
10            "description": "List of legions"
11          }
12        }
13      }
14    }
15  }
16}

What is Swagger?

Swagger is a set of tools for working with the OpenAPI specification. In the context of NestJS, the most important one is Swagger UI - an interactive documentation page that allows you to browse and test API endpoints directly from the browser.

Swagger UI is like the Forum Romanum of our API - a place where every citizen (developer) can see the available services of the Empire, test them, and understand how they work.

Why is API documentation important?

Just as the Roman Empire could not function without written laws and decrees, modern APIs should not exist without documentation:

1. Communication between teams - frontend and backend speak the same language
2. Onboarding new developers - new legionaries quickly learn the API structure
3. Testing - Swagger UI allows testing endpoints without writing code
4. Client code generation - automatic SDK generation based on the specification
5. API contracts - a clear agreement between API provider and consumer

@nestjs/swagger - The Scribe of the Empire

In NestJS, we use the

@nestjs/swagger

package to create documentation. This package automatically generates the OpenAPI specification based on decorators in our code:

1import { Controller, Get } from '@nestjs/common';
2import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
3
4@ApiTags('Legiones')
5@Controller('legiones')
6export class LegionController {
7  @ApiOperation({ summary: 'Get all legions' })
8  @ApiResponse({ status: 200, description: 'List of Empire legions' })
9  @Get()
10  findAll() {
11    return [
12      { name: 'Legio X Gemina', location: 'Pannonia' },
13      { name: 'Legio III Augusta', location: 'Africa' },
14    ];
15  }
16}

Each

@Api...

decorator is like an official seal on a document - it gives it an official character and describes the purpose of the endpoint.

Basic Swagger Decorators

| Decorator | Roman Analogy | Description | |-----------|---------------|-------------| |

@ApiTags()

| Book of annals | Groups endpoints into sections | |

@ApiOperation()

| Imperial decree | Describes a single endpoint | |

@ApiResponse()

| Response edict | Defines possible responses | |

@ApiProperty()

| Seal on a document | Describes a field in a DTO | |

@ApiBearerAuth()

| Legion signum | Marks an endpoint as protected |

Practical Exercise

Take a look at the code below, which shows the basic Swagger configuration in a NestJS project: