SESSION 081 — API Documentation

CONCEPTS.UNLOCKED

📖

OpenAPI / Swagger

The industry standard for describing REST APIs. A YAML/JSON file that defines every endpoint, parameter, request body, and response. Machine-readable — tools generate docs, SDKs, and tests from it.

🤖

Auto-Generating Docs

Write JSDoc comments → generate OpenAPI spec. swagger-jsdoc reads your route comments and produces a spec. swagger-ui-express renders it as an interactive page.

🏷️

API Versioning

/api/v1/ prefix for all routes. When you make breaking changes, create /api/v2/ — old clients keep working on v1. Version in URL is the simplest and most visible strategy.

📝

Documentation-Driven Development

Write the API spec first, then implement. The spec becomes the contract between frontend and backend. Teams can work in parallel — frontend mocks from the spec, backend implements it.

🧪

Try It Out

Interactive docs let you test endpoints. Swagger UI has a "Try it out" button — fill in parameters, click Execute, see the real response. API documentation that doubles as a testing tool.

📋

Response Schemas

Define the shape of every response. What fields does /api/images return? What type is each field? Schema definitions serve as both documentation and validation contracts.

HANDS-ON.TASKS

Set Up Swagger

▶

npm install swagger-jsdoc swagger-ui-express

const swaggerJsdoc =
  require('swagger-jsdoc');
const swaggerUi =
  require('swagger-ui-express');

const swaggerSpec = swaggerJsdoc({
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'PixelCraft API',
      version: '1.0.0',
      description:
        'Image editing platform API',
    },
    servers: [
      { url: '/api/v1',
        description: 'v1' },
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        },
      },
    },
  },
  apis: ['./routes/*.js'],
});

app.use('/api/docs',
  swaggerUi.serve,
  swaggerUi.setup(swaggerSpec, {
    customSiteTitle: 'PixelCraft API Docs',
  })
);

Document Endpoints with JSDoc

▶

/**
 * @openapi
 * /images:
 *   get:
 *     summary: Get user's images
 *     tags: [Images]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 20
 *         description: Items per page
 *     responses:
 *       200:
 *         description: List of images
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 images:
 *                   type: array
 *                   items:
 *                     $ref: '#/components
 *                       /schemas/Image'
 *                 total:
 *                   type: integer
 *       401:
 *         description: Unauthorized
 */
router.get('/images',
  authenticate, getImages);

Define Schemas

▶

/**
 * @openapi
 * components:
 *   schemas:
 *     Image:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *           example: "507f1f77bcf86cd7"
 *         title:
 *           type: string
 *           example: "Sunset photo"
 *         thumbnailUrl:
 *           type: string
 *           example: "/thumbnails/abc.webp"
 *         width:
 *           type: integer
 *           example: 1920
 *         height:
 *           type: integer
 *           example: 1080
 *         createdAt:
 *           type: string
 *           format: date-time
 *     Error:
 *       type: object
 *       properties:
 *         error:
 *           type: string
 *         requestId:
 *           type: string
 */

Add API Versioning

▶

// Version all routes under /api/v1/
const v1Router = express.Router();

v1Router.use('/auth', authRoutes);
v1Router.use('/images', imageRoutes);
v1Router.use('/analytics',
  analyticsRoutes);

app.use('/api/v1', v1Router);

// When v2 is needed:
// app.use('/api/v2', v2Router);
// v1 keeps working for old clients

URL versioning (/api/v1/) is the simplest approach. Other strategies: header versioning (Accept: application/vnd.api.v1+json) or query param (?version=1). URL is most visible and easiest to reason about.

Document All Endpoints

▶

Add JSDoc/OpenAPI comments to every route: POST /auth/register, POST /auth/login, GET /images, POST /images/upload, GET /images/:id, DELETE /images/:id, GET /analytics/daily-active-users. Include request body examples and all possible response codes.

Close the Ticket

▶

git switch -c feature/PIXELCRAFT-068-api-docs
git add server/
git commit -m "Add Swagger API docs + versioning (PIXELCRAFT-068)"
git push origin feature/PIXELCRAFT-068-api-docs
# PR → Review → Merge → Close ticket ✅

CS.DEEP-DIVE

API design is interface design.

An API is a contract between systems. Good API design follows the same principles as good UI design — consistency, predictability, and clear feedback.

// API design principles:

Consistency
  All endpoints follow the same pattern
  GET /resources, POST /resources
  GET /resources/:id

Predictability
  If GET /images works, GET /users
  should work the same way

Clear errors
  400 = your fault (bad input)
  401 = not logged in
  403 = logged in, not authorized
  404 = doesn't exist
  500 = our fault (bug)

// Famous APIs to study:
Stripe  → gold standard of API design
GitHub → REST and GraphQL both
Twilio → excellent error messages

// "Your API is a user interface.
// Developers are users too."

REF.MATERIAL

ARTICLE

OpenAPI Specification 3.0

Swagger / SmartBear

The official OpenAPI spec: paths, operations, parameters, request bodies, responses, schemas, security. The industry standard for API description.

OPENAPIOFFICIALESSENTIAL

VIDEO

RESTful APIs in 100 Seconds — Fireship

Fireship

Quick overview of REST principles: resources, HTTP methods, status codes, and why API design matters. The context behind the docs.

RESTQUICK

ARTICLE

Stripe API Reference

Stripe

The gold standard of API documentation. Study the layout, examples, error handling, and developer experience. This is what great docs look like.

STRIPEREFERENCEESSENTIAL

ARTICLE

swagger-jsdoc — GitHub

Surnet

Generate OpenAPI specs from JSDoc comments in your Express routes. Write docs alongside your code — they stay in sync automatically.

SWAGGERNODE.JS

VIDEO

Swagger UI Tutorial — Academind

Academind

Setting up Swagger UI with Express: defining specs, documenting endpoints, adding authentication, and customizing the UI.

SWAGGERTUTORIAL

API DOCUMENTATION