How do you document an API? | API Interview Questions

What You'll Learn

Documentation tools
What to include
OpenAPI/Swagger basics

Documentation Tools

Swagger/OpenAPI - Industry standard
Postman - Collections with docs
Redoc - Beautiful API docs
ReadMe - Interactive docs

What to Include

Authentication - How to authenticate
Endpoints - All available routes
Parameters - Query, path, body params
Responses - Success and error examples
Rate limits - Usage restrictions
Examples - Code samples

OpenAPI Example

config.ymlYAML

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        200:
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        201:
          description: User created
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string