Home / Technical writer's guide to API documentation

Technical writer’s guide to API documentation

This directory provides a comprehensive learning journey for technical writers working with REST API documentation. The guide focuses on two primary approaches to creating OpenAPI documentation, each with distinct workflows and use cases.

Choose your learning path

New to OpenAPI documentation? Start with generated documentation to see how documentation works, then explore manual YAML writing.

Working with developers who maintain the code? Focus on generated documentation.

Need full control over documentation content and structure? Focus on manual YAML writing.

Want to understand the complete workflow? Follow all guides: generated documentation (45-60 min) → manual YAML writing (60-90 min) → testing (45-60 min) → publishing (30-45 min).

Approach 1: Generated documentation (code-first)

What it is: Documentation automatically generated from annotations in Java source code.

How it works:

  • Developers add @Operation, @ApiResponse, @Parameter annotations to code
  • SpringDoc automatically generates OpenAPI specification
  • Documentation updates when code changes

Learning time: 45-60 minutes

Your next step: → Generated documentation guide

Approach 2: Manual YAML writing (design-first)

What it is: Hand-crafted OpenAPI specifications written in YAML format.

How it works:

  • Design API specification before or alongside implementation
  • Write complete OpenAPI YAML files using editors
  • Validate specifications against running API
  • Import into testing tools and documentation platforms

Learning time: 60-90 minutes

Your next step: → Manual YAML writing guide

Testing the API (both approaches)

After learning either or both documentation approaches, understand how to validate your work:

Your next step: → Testing and validation guide

Learning time: 45-60 minutes

Publishing API documentation

Once you’ve created and tested your documentation, learn how to deploy it for public consumption by API users:

What it covers: Static HTML generation, GitHub Pages deployment, cloud platforms, and production best practices

Your next step: → API documentation publishing guide

Learning time: 30-45 minutes

Reference materials

Quick access to examples, comparisons, and troubleshooting: