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

Practical Exercise

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

1// Imperium Chronicles - Introduction to Swagger
2import { Controller, Get } from '@nestjs/common';
3import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
4
5// Swagger decorators describe endpoints like imperial chronicles
6// Each decorator adds information to the API documentation
7
8@ApiTags('Imperium')
9@Controller()
10export class AppController {
11  @ApiOperation({ summary: 'Status Imperium' })
12  @ApiResponse({ status: 200, description: 'Imperium working correctly' })
13  @Get()
14  getStatus() {
15    return {
16      imperium: 'Roma Aeterna',
17      status: 'Active',
18      annales: 'Swagger UI available at /api/docs',
19    };
20  }
21
22  @ApiOperation({ summary: 'API information' })
23  @ApiResponse({ status: 200, description: 'Imperium API metadata' })
24  @Get('info')
25  getInfo() {
26    return {
27      name: 'Imperium Romanum API',
28      version: '1.0',
29      description: 'API for managing legions and provinces',
30      documentation: '/api/docs',
31    };
32  }
33}
34
35// OpenAPI / Swagger is a standard for describing REST APIs
36// @nestjs/swagger generates the documentation automatically
37// Swagger UI lets you browse and test endpoints
38
39console.log("Swagger = Imperium Chronicles");
40console.log("OpenAPI = API description standard");
41console.log("@ApiTags = Books of annals (grouping)");
42console.log("@ApiOperation = Imperial decree (endpoint description)");
43console.log("@ApiResponse = Response edict (possible responses)");
44