How to Document and Test a REST API?

💡 Summary (TL;DR):
OpenAPI (Swagger): The industry standard. It lets you define your API schemas as JSON/YAML and generate both documentation (Swagger UI/Redoc) and automatic client code.
Postman: A rich platform for team collaboration, automated test scenarios, and mock servers.
Modern Approach: These days, instead of writing documentation by hand, the preferred path is to derive OpenAPI schemas automatically from your code using libraries like FastAPI (Python), NestJS (TS), or Fastify.
Modern Clients: Instead of the Advanced Rest Client (ARC), developers now reach for modern tools like the Git-friendly, open-source Bruno or the VS Code-integrated Thunder Client.

This article is part of the RESTful API Design series. If you haven't read the other articles yet, I recommend starting with them first:

Writing documentation is usually far harder and far more neglected than coding the API itself. While there are libraries that claim to automate it, the annotations or decorators you need to add to your code so those tools produce correct output can sometimes be just as much work as writing the docs by hand.

Here is the critical information that good REST API documentation must contain:

API Endpoints and HTTP Methods: Which resources are accessed through which URIs? (e.g., GET /users, POST /users)
Parameters: Which parameters are expected in the query, path, or body? Which are required and which are optional? What are their data types?
Request Examples: Payload contents and HTTP header information (e.g., Content-Type: application/json).
Response Schema and Examples: The body structure of both successful (200 OK, 201 Created) and error responses.
Error Codes: Possible HTTP error status codes (400, 401, 403, 404, 500) and the format of the returned error messages.
Authentication & Authorization: Does accessing the endpoint require a JWT token, an API Key, or OAuth2? If so, how should it be sent?
Rate Limiting: The maximum number of requests a client may make per minute/second.

API Design Approaches: Design-First vs. Code-First

When planning your API documentation, you typically pick one of two core approaches:

1. Design-First

Here you design the API contract according to the OpenAPI specification, in YAML or JSON format, before writing any code.

Advantage: Frontend and backend developers can start working simultaneously against a shared contract. The schema you design can be turned into a fake API server instantly with mock tools like Prism.
Tools: Swagger Editor, Stoplight Studio, Apicurio.

2. Code-First

Here you write the backend code first and derive the documentation automatically from the type definitions, decorators, or comments inside the code.

Advantage: When the code changes, the documentation updates automatically, preventing the code and the docs from drifting out of sync.
Libraries: FastAPI (Python — comes built-in), NestJS (@nestjs/swagger — TypeScript), Fastify (@fastify/swagger — Node.js), zircote/swagger-php (PHP).

The Industry Standard: OpenAPI and Swagger

What is OpenAPI?

OpenAPI is an official specification that lets you describe RESTful APIs in a language-agnostic way. It documents all the inputs and outputs of your API in a standard JSON or YAML file.

What is Swagger?

Swagger is the ecosystem of tools used to create, visualize, and consume the OpenAPI specification (Swagger UI, Swagger Editor, Swagger Codegen).

Below is an example OpenAPI 3.1 YAML schema for an API endpoint that returns a user's details:

openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Retrieve the details of a specific user
      parameters:
        - name: id
          in: path
          required: true
          description: The user's unique ID value
          schema:
            type: integer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Successful request response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 42
                  name:
                    type: string
                    example: "Evren Bal"
        '401':
          description: Unauthorized access (Token missing or invalid)
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Modern Documentation Interfaces

Once you've prepared the OpenAPI YAML/JSON file, you need to present it to users through a polished interface:

Swagger UI: The industry's oldest and most popular interface. It lets you test requests by firing them directly from the browser ("Try it out").
Redoc: A great, modern, three-panel static documentation interface (left navigation, center content, right-hand code blocks), especially for large APIs. Its readability is far higher than Swagger UI's.
Scalar: An extremely fast, interactive, and elegant OpenAPI client whose popularity has surged recently. It includes a built-in API testing tool (REST client).
Stoplight Elements: A modern, Web Component–based alternative that you can easily integrate into your own site.

API Testing and Documentation Tools

Beyond documentation, the tools you use to test API requests during development matter just as much:

1. Postman

The most widely used platform for API testing, sharing collections across a team, and running end-to-end integration tests. It lets you write JavaScript-based test scripts and integrate them into CI/CD pipelines (via Newman or the Postman CLI). That said, because recent versions have leaned heavily into cloud-based and commercial features, some developers find it bloated.

2. Bruno (Open-Source & Git-Friendly)

The strongest open-source alternative to Postman. Its biggest advantage is that it stores your API request collections not in encrypted or opaque databases but in plain-text files (.bru files) that can live directly in your project's Git repository. This makes version control extremely easy.

3. VS Code Extensions (Thunder Client / RapidAPI Client)

Great solutions for those who want to fire off requests quickly without leaving the editor. They're lightweight and practical.

Comparison Table

Tool	Purpose	Advantages	Disadvantages
OpenAPI / Swagger	Schema & Visual Interface	Language-agnostic standard, automatic code generation, wide ecosystem	Writing the YAML/JSON schema by hand is complex
Postman	API Testing & Automation	Rich interface, mock servers, powerful test scripts	Cloud dependency, an increasingly heavy interface, paid tiers for team features
Bruno	Git-Friendly API Testing	Fully open-source, keeps collections as plain text in Git	Its ecosystem and integration tooling aren't as broad as Postman's

Frequently Asked Questions (FAQ)

How should we protect API documentation in a production environment?

Leaving your entire API documentation publicly accessible on a live server can introduce security risks. To prevent that:

Add a Basic Authentication layer (username/password) in front of the Swagger/Redoc endpoints.
Only allow requests coming from specific IP addresses (e.g., your office IP or VPN).
Use environment variables (ENABLE_SWAGGER=false) to fully disable the documentation endpoint in production.

How do I create a mock server for the frontend using my OpenAPI schema?

If you have an OpenAPI spec file (api.yaml), you can spin up a fake server in seconds using the Prism library:

npx @stoplight/prism-cli mock api.yaml

This command starts a local server that uses the example data defined in your schema to return JSON responses matching your requests.

Official Resources & Documentation

In the end, well-designed documentation that follows the standards makes your API easier to use, reduces errors, and speeds up integration between frontend and backend teams. Adopting the OpenAPI (Swagger/Scalar) standard in your projects will save you time in the long run.

Changelog

2026-06-20: Updated the article's content to align with modern OpenAPI 3.1 standards. Enriched it with design approaches (Design-First vs. Code-First), mock server tools (Prism), modern documentation tools (Redoc, Scalar), and the Git-friendly API client Bruno.
2022-05-11: Revised the article summary.