API Documentation with OpenAPI and Stoplight — Practical Guide

DodaTech Updated 2026-06-23 7 min read

In this tutorial, you'll learn about API Documentation with OpenAPI and Stoplight. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

API documentation is a technical reference that describes how to use an API effectively, including endpoints, parameters, request examples, response formats, error codes, and authentication requirements for developers.

What You'll Learn

You will learn to create professional API documentation using OpenAPI specification and Stoplight Studio, design interactive documentation portals, write clear endpoint descriptions, and maintain docs that stay in sync with your API.

Why API Documentation Matters

Documentation is the most visited page of any API product. Developers judge an API by its documentation quality. Well-documented APIs reduce support tickets by 60 percent, increase adoption rates, and shorten integration time from days to hours.

Real-World Use

DodaTech publishes public API documentation for all products through a Stoplight portal. Doda Browser sync API docs include interactive examples, DodaZIP update API docs show version history and changelogs, and Durga Antivirus Pro API docs provide threat data schemas with real-world examples.

API Documentation Learning Path

flowchart LR
  A[OpenAPI Spec] --> B[Documentation Design]
  B --> C[Stoplight Studio]
  C --> D[Writing Endpoints]
  D --> E[Examples & Schemas]
  E --> F[Interactive Docs]
  F --> G[Publishing & Hosting]
  B:::current

  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Prerequisites

Understand OpenAPI Specification Guide and RESTful Api Design Best Practices. Familiarity with Postman for API Testing helps. Basic YAML and JSON knowledge is required.

Why Stoplight?

Stoplight is an Api Design and documentation platform that integrates with OpenAPI specifications. It offers:

Visual API designer with real-time OpenAPI validation
Collaborative editing for teams
Hosted documentation portal
Mock servers for testing
Change log and version tracking
Code examples in multiple languages

Setting Up Stoplight

Step 1: Create a Stoplight Account

Visit stoplight.io and sign up for a free account. The free tier includes unlimited public projects and up to three private projects.

Step 2: Create a New Project

Click New Project
Select OpenAPI 3.1
Name it DodaTech Users API
Choose Design-first workflow

Step 3: Import Existing OpenAPI Spec

If you already have an OpenAPI specification, import it:

# Using Stoplight CLI
npm install -g @stoplight/cli
stoplight import openapi.yaml --project "DodaTech Users API"

Designing API Documentation

General Guidelines

Write for developers who are seeing your API for the first time
Include complete request and response examples
Explain error codes and how to handle them
Provide code samples in multiple languages
Keep descriptions concise but complete

Writing Endpoint Descriptions

paths:
  /users:
    get:
      summary: List all users
      description: |
        Retrieves a paginated list of users from the DodaTech platform.
        Results are sorted by creation date in descending order.
        Use the page and limit parameters to control pagination.

        **Access**: Requires read:users scope
        **Rate limit**: 100 requests per minute

        ### Use cases
        - Sync user directory for Doda Browser
        - Audit user access for Durga Antivirus Pro
        - Generate user reports
      operationId: listUsers
tags:
        - Users
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed)
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: sort
          in: query
          description: Sort field and direction
          schema:
            type: string
            enum: [created_at:asc, created_at:desc, name:asc, name:desc]
            default: created_at:desc
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
        "401":
          description: Authentication required
        "429":
          description: Rate limit exceeded

Adding Code Examples

paths:
  /users:
    get:
      x-codeSamples:
        - lang: curl
          source: |
            curl -X GET "https://api.dodatech.com/v1/users?page=1&limit=20" \
              -H "Authorization: Bearer YOUR_TOKEN" \
              -H "Accept: application/json"
        - lang: Python
          source: |
            import requests

            response = requests.get(
                "https://api.dodatech.com/v1/users",
                headers={"Authorization": "Bearer YOUR_TOKEN"},
                params={"page": 1, "limit": 20}
            )
            print(response.json())
        - lang: JavaScript
          source: |
            fetch("https://api.dodatech.com/v1/users?page=1&limit=20", {
              headers: {
                "Authorization": "Bearer YOUR_TOKEN",
                "Accept": "application/json"
              }
            })
            .then(res => res.json())
            .then(data => console.log(data));
        - lang: Go
          source: |
            package main

            import (
                "fmt"
                "net/http"
                "io"
            )

            func main() {
                url := "https://api.dodatech.com/v1/users?page=1&limit=20"
                req, _ := http.NewRequest("GET", url, nil)
                req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
                resp, _ := http.DefaultClient.Do(req)
                body, _ := io.ReadAll(resp.Body)
                fmt.Println(string(body))
            }

Documenting Schemas

components:
  schemas:
    User:
      title: User
      description: |
        A user account on the DodaTech platform. Users can be human
        accounts or service accounts for automated integrations.

        **Permissions**:
        - Users with `admin` role have full access
        - Users with `member` role have read and write access
        - Users with `viewer` role have read-only access
      type: object
      required:
        - id
        - name
        - email
        - role
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier assigned by the system
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          description: Display name of the user
          minLength: 1
          maxLength: 100
          example: "Alice Johnson"
        email:
          type: string
          format: email
          description: Primary email address for notifications
          example: "alice@example.com"
        role:
          type: string
          enum: [admin, member, viewer]
          description: Authorization role determining access level
          example: "admin"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the account was created
          example: "2026-01-15T10:30:00Z"

Building an Interactive Documentation Portal

Stoplight generates a hosted documentation portal from your OpenAPI spec.

Portal Features

Interactive API console where users can send real requests
Language-specific code examples
Search across all endpoints
Dark mode
Custom branding and domain

Customizing the Portal

# stoplight-project.json
{
  "name": "DodaTech API Docs",
  "version": "1.0.0",
  "branding": {
    "primaryColor": "#FF6600",
    "logo": "https://dodatech.com/logo.svg",
    "favicon": "https://dodatech.com/favicon.ico"
  },
  "integration": {
    "baseUrl": "https://api.dodatech.com/v1",
    "showMockServer": true,
    "showCodeSamples": true,
    "defaultLanguage": "curl"
  }
}

Using Stoplight Elements (Open Source)

For self-hosted documentation, use Stoplight Elements:

<!DOCTYPE HTML>
<HTML>
<head>
  <title>DodaTech API Documentation</title>
  <link rel="stylesheet" href="HTTPS://unpkg.com/@stoplight/elements/styles.min.CSS">
</head>
<body>
  <div id="API-docs"></div>
  <script src="HTTPS://unpkg.com/@stoplight/elements/web-components.min.js"></script>
  <script>
    const API = document.createElement("elements-API");
    API.apiDescriptionUrl = "/openapi.YAML";
    API.router = "hash";
    API.layout = "sidebar";
    document.getElementById("API-docs").appendChild(API);
  </script>
</body>
</HTML>

Maintaining Documentation

Keep documentation in sync with your API:

Store OpenAPI spec in your Repository alongside your code
Add API doc review to your code review Process
Run automated validation on every Pull Request
Use Stoplight CI to detect spec changes

# .github/workflows/API-docs-check.yml
name: API Doc Check
on: [pull_request]
jobs:
  validate:
    runs-on: Ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate OpenAPI Spec
        run: npx @stoplight/spectral-cli lint openapi.YAML
      - name: Check for Breaking Changes
        run: |
          npx @stoplight/diff-cli diff \
            --BASE origin/main:openapi.YAML \
            --head HEAD:openapi.YAML

Common Errors

Incomplete examples — Providing curl examples without showing the actual response. Always show both request and response. Developers learn by reading examples.
Missing error documentation — Documenting only successful responses. Every error code needs a description and example. Developers spend most of their time handling errors.
Stale documentation — Updating the API without updating docs. Integrate doc generation into your build pipeline. Reject PRs that change API behavior without updating the spec.
Too much jargon — Using internal team terminology in public docs. Write for a developer who has never seen your API. Define every term the first time it appears.
No authentication examples — Showing endpoints without explaining how to authenticate. Every endpoint description should include an auth example. Show where the token goes and how to get one.
Inconsistent formatting — Mixing YAML styles or using inconsistent description formats. Use a linter like Spectral to enforce consistent documentation style.
Missing rate limit information — Not documenting rate limits. Developers need to know limits to implement proper retry logic. Include rate limit headers in response examples.

Practice Questions

What are the key components of a well-documented API endpoint?
How does Stoplight help maintain API documentation?
Why should you include error response examples in documentation?
What is the difference between design-first and code-first documentation?
How can you automate documentation validation in CI/CD?

Challenge

Create a complete documentation portal for a file storage API. Write OpenAPI 3.1 spec for at least eight endpoints (upload, download, list, delete, share, search, metadata, trash). Include code examples in curl, Python, JavaScript, and Go. Add schema definitions for File, Folder, and Share objects. Publish as a Stoplight portal. Write a CI workflow that validates the spec and checks for breaking changes on every PR.

FAQ

What is the difference between API documentation and API specification? API documentation is the human-readable guide explaining how to use an API. API specification (OpenAPI) is the machine-readable definition of the API contract. Documentation is generated from the specification.

Should I use Stoplight or Swagger UI for documentation? Swagger UI is free and open-source, great for simple documentation. Stoplight offers a complete platform with design tools, collaboration, hosted portals, and mock servers. Choose Swagger UI for small projects and Stoplight for team-based API development.

How often should I update API documentation? Update documentation every time the API changes. The best approach is to generate documentation from the OpenAPI spec and keep the spec in the same Repository as the implementation.

Can I host Stoplight documentation on my own domain? Yes. Stoplight supports custom domains on paid plans. You can also self-host using Stoplight Elements, the open-source documentation component.

What is Spectral? Spectral is an OpenAPI linter that enforces documentation style rules. It catches missing descriptions, inconsistent naming, and incomplete schemas before documentation is published.

← Previous Rate Limiting and Throttling for APIs — Complete Guide Next → GraphQL API Design and Best Practices — Complete Guide

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Development