Technical Writing and Documentation 101: API Documentation Tools (SwaggerHub, Redocly, Postman)

API Documentation Tools (SwaggerHub, Redocly, Postman)

API Documentation Tools Study Guide: SwaggerHub, Redocly, Postman

A practical, portfolio-ready guide for aspiring and modernizing technical writers

What This Is

API documentation is the instruction manual for developers using your API—it explains endpoints, parameters, authentication, and error codes. Without clear docs, even the best API is unusable.
Example: Stripe’s API reference lets developers integrate payments in minutes by showing request/response examples, SDK snippets, and interactive testing. This guide covers tools to design, test, and publish API docs efficiently, whether you’re documenting a REST API for a fintech startup or a cloud service’s SDK.

Key Terms & Tools

• OpenAPI (formerly Swagger):
  A machine-readable specification (YAML/JSON) to describe REST APIs. Enables auto-generated docs, client SDKs, and server stubs. Tools: SwaggerHub, Redocly, Stoplight.

• Swagger UI:
  An open-source tool that renders OpenAPI specs as interactive docs (try it at petstore.swagger.io). Lets users test endpoints directly in the browser.

• ReDoc:
  A sleek, three-panel alternative to Swagger UI (used by Microsoft, GitHub). Focuses on readability with collapsible sections and Markdown support.

• SwaggerHub:
  A SaaS platform by SmartBear for hosting, collaborating on, and publishing OpenAPI specs. Integrates with CI/CD pipelines and version control.

• Redocly:
  A suite of tools (CLI, editor, hosting) for OpenAPI workflows. Includes redoc-cli to generate static docs and redocly lint to validate specs.

• Postman:
  A collaboration platform for API development. Lets you test endpoints, generate docs from collections, and mock APIs. Key feature: Postman’s "Publish Docs" button auto-generates a public portal.

• Docs-as-Code:
  Treating docs like code—stored in Git, written in Markdown/AsciiDoc, built with static site generators (e.g., Docusaurus, MkDocs), and reviewed via pull requests.

• API Blueprint:
  A Markdown-based alternative to OpenAPI (used by Apiary). Less common but simpler for quick prototyping.

• Static Site Generators (SSGs):
  Tools like Docusaurus, Hugo, or MkDocs that convert Markdown files into fast, versioned documentation sites. Example: Stripe’s docs use a custom SSG.

• Mock Servers:
  Simulate API responses before the backend is ready. Tools: Postman Mock Servers, Prism (by Stoplight), SwaggerHub Mocking.

• SDKs (Software Development Kits):
  Language-specific libraries (e.g., Python, Java) that wrap API calls. Docs should include SDK installation and usage examples.

• Webhooks:
  "Reverse APIs" where the server sends data to a client’s URL. Docs must explain event payloads, authentication, and retry logic.

Step-by-Step / Process Flow

How to document an API from scratch (or update existing docs):

1. Gather Requirements & Spec
2. Get the OpenAPI spec (YAML/JSON) from developers. If none exists, write one using:
   • SwaggerHub Editor (web-based, real-time preview).
   • Redocly’s create-openapi-repo (CLI tool to scaffold a spec).

3. Pro tip: Use redocly lint to catch errors early (e.g., missing description fields).

4. Test the API

5. Import the OpenAPI spec into Postman to:
   • Send requests and validate responses.
   • Save examples for docs (Postman auto-generates code snippets in 10+ languages).

6. Example: Test a GET /users endpoint with query params like ?limit=10.

7. Write the Docs

8. For OpenAPI-based tools (SwaggerHub/Redocly):
   • Fill in description fields in the spec (supports Markdown).
   • Add examples for request/response bodies.
   • Use x-codeSamples (OpenAPI 3.1) to embed SDK snippets.
9. For Postman:
   • Annotate collections with Markdown (e.g., # Authentication).
   • Add visual examples (screenshots of Postman’s request/response tabs).

10. Pro tip: Use Mermaid.js in Markdown to add sequence diagrams (e.g., OAuth flow).

11. Generate & Style the Docs

12. SwaggerHub: Click "Publish" to deploy a Swagger UI or ReDoc page.
13. Redocly: Run redoc-cli build openapi.yaml to generate a static HTML file.
14. Postman: Click "Publish Docs" to create a public portal (customizable with CSS/JS).

15. Example: Twilio’s API docs use ReDoc with a custom theme.

16. Add Tutorials & Guides

17. Write conceptual docs (e.g., "How OAuth Works") and tutorials (e.g., "Build a Payment App in 10 Minutes").
18. Use a static site generator (e.g., Docusaurus) to combine API reference + guides in one site.

19. Example: Stripe’s "Build a Subscription Service" tutorial.

20. Review & Deploy

21. Submit the OpenAPI spec or Postman collection for developer review (e.g., via GitHub PR).
22. Set up CI/CD (e.g., GitHub Actions) to auto-deploy docs on merge.
23. Pro tip: Use SwaggerHub’s "Compare" feature to diff API versions.

Common Mistakes

• Mistake: Writing docs after the API is built.
  Correction: Collaborate with developers during design (e.g., review the OpenAPI spec before coding). Why: Early feedback catches inconsistencies (e.g., naming conventions, missing error codes).

• Mistake: Assuming the OpenAPI spec is "self-documenting." Correction: Add human-readable descriptions for every endpoint, parameter, and response. Why: A spec is for machines; docs are for humans. Example: Instead of GET /users, write: yaml description: |
Retrieves a paginated list of users. Use `limit` and `offset` for pagination.
Example: `GET /users?limit=10&offset=20`

• Mistake: Only showing curl examples.
  Correction: Include SDK snippets (Python, JavaScript, etc.) and Postman collections. Why: Developers prefer copy-paste-ready code. Example: javascript // Node.js example using Stripe SDK const stripe = require('stripe')('sk_test_123'); const customers = await stripe.customers.list({ limit: 10 });

• Mistake: Ignoring error codes.
  Correction: Document every HTTP status code (e.g., 401 Unauthorized, 429 Too Many Requests) with examples. Why: Developers need to handle errors gracefully. Example: yaml responses:
'401':
description: Unauthorized. Missing or invalid API key.
content:
application/json:
example: { "error": "Invalid API key" }

• Mistake: Not versioning docs.
  Correction: Use semantic versioning (e.g., v1, v2) and deprecation notices. Why: Breaking changes break apps. Example: Add a banner:

  
  

  ⚠️ Deprecation Notice: GET /v1/users will be removed on 2024-06-01. Migrate to GET /v2/users.

  
  

Tech Writing Interview / Portfolio Tips

• What Hiring Managers Look For:
• Portfolio: Show 3 types of API docs:
  1. Reference (e.g., OpenAPI spec + Swagger UI/ReDoc).
  2. Tutorial (e.g., "Build a Weather App with Our API").
  3. Conceptual guide (e.g., "Authentication with OAuth 2.0").
• Tools: Highlight experience with SwaggerHub, Postman, or Redocly (even if just a demo project).

• Process: Explain how you collaborate with developers (e.g., "I review OpenAPI specs in PRs and test endpoints in Postman").

• Tricky Distinctions:

• Swagger UI vs. ReDoc:
  • Swagger UI: Interactive (lets users send requests), but cluttered UI.
  • ReDoc: Cleaner, better for readability, but no interactivity.
• Reference vs. Guide:
  • Reference: Lists endpoints/parameters (e.g., API reference).
  • Guide: Explains concepts (e.g., "How to Handle Webhooks").

• Tutorial vs. How-To:

  
  
  • Tutorial: Teaches by building (e.g., "Create a Chat App").
  • How-To: Solves a specific problem (e.g., "Reset a Forgotten Password").

• Portfolio Project Ideas:

• Fake API: Document a mock API (e.g., a "Pet Store" API) using SwaggerHub + ReDoc.
• Postman Collection: Publish a public Postman collection with Markdown annotations.
• SDK Docs: Write docs for a Python/Node.js SDK (even if it’s just a wrapper around a public API like GitHub’s).

Quick Check Questions

1. Scenario: A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
   Answer: Set up CI/CD pipelines to auto-generate docs from the OpenAPI spec on every code merge. Why: Automation reduces human error and keeps docs current.

2. Scenario: Your team uses Postman for API development but wants to switch to OpenAPI. How would you migrate the docs?
   Answer: Export the Postman collection to OpenAPI (Postman supports this natively), then use Redocly or SwaggerHub to generate docs. Why: OpenAPI is the industry standard for machine-readable specs.

3. Scenario: A stakeholder asks, "Why can’t we just use Swagger UI for our entire documentation site?" What’s your response?
   Answer: Swagger UI is great for reference docs but lacks support for tutorials, guides, or conceptual content. Use a static site generator (e.g., Docusaurus) to combine Swagger UI with other doc types. Why: Developers need more than just endpoint lists—they need examples, use cases, and troubleshooting tips.

Last-Minute Cram Sheet

1. OpenAPI 3.1 vs. 2.0: 3.1 adds webhooks, examples keyword, and better JSON Schema support. ⚠️ Always use 3.1 for new projects.
2. Markdown in OpenAPI: Use | for multi-line descriptions (e.g., description: |).
3. Postman Docs: Publish collections as public portals (customizable with CSS/JS).
4. SwaggerHub: Supports mock servers and versioning (e.g., v1, v2).
5. ReDoc: Use redoc-cli to generate static HTML (redoc-cli build openapi.yaml).
6. Docs-as-Code: Store docs in Git, write in Markdown/AsciiDoc, review via PRs.
7. SDK Snippets: Always include installation steps + authentication examples.
8. Error Codes: Document every HTTP status code (e.g., 400, 401, 500).
9. Tutorials: Teach by building (e.g., "Create a To-Do App"). ⚠️ Not the same as a how-to guide.
10. CI/CD: Use GitHub Actions or SwaggerHub CI to auto-deploy docs on merge.

Next Steps:
- Try documenting a public API (e.g., GitHub, Spotify) using SwaggerHub or Postman.
- Build a portfolio project combining API reference + tutorial (e.g., "Build a Weather App with OpenWeatherMap API").
- Explore Redocly’s CLI (npm install -g @redocly/cli) to lint and generate docs locally.