Skip to main content

Module 2: API Documentation & OpenAPI

This project demonstrates professional API documentation practices by documenting the Chimoney REST API using a Docs-as-Code approach with Docusaurus and OpenAPI integration.

Live Site​

đź”— View Live Documentation

Project Overview​

This documentation site provides comprehensive guidance for developers integrating with the Chimoney payment API. The project showcases how modern API documentation combines narrative guides with interactive API references to create a seamless developer experience.

Documentation Structure​

The documentation is organized into three key sections:

1. Introduction

  • Overview of Chimoney's capabilities
  • Key features and use cases
  • Target audience identification

2. Getting Started Guide

  • Prerequisites and account setup
  • Authentication and API keys
  • First API call tutorial
  • Troubleshooting common issues

3. API Reference

  • Retrieve All Wallets – Get multicurrency wallet balances
  • Send Payment – Issue Chimoney payouts to recipients
  • Redeem Gift Card – Convert Chimoney to gift cards

Each endpoint includes:

  • Overview with use cases
  • Request/response examples
  • Error handling scenarios
  • cURL examples for testing
  • Best practices

OpenAPI Integration​

How It Works​

This project leverages the OpenAPI Specification to automate API documentation generation. Here's the workflow:

1. API Specification

# chimoney-openapi.yaml
openapi: 3.0.0
info:
  title: Chimoney API
  version: 0.2.4
paths:
  /multicurrency-wallets/list:
    get:
      summary: Retrieve All Wallets
      # ... endpoint details

2. Docusaurus Plugin Integration

The docusaurus-plugin-openapi-docs plugin reads the OpenAPI YAML file and automatically generates interactive API documentation pages.

3. Automated Documentation

When the OpenAPI spec is updated, the documentation automatically reflects:

  • Endpoint paths and methods
  • Request parameters and body schemas
  • Response schemas and examples
  • Authentication requirements

Benefits:

  • Single source of truth – API spec and docs stay synchronized
  • Interactive testing – Developers can test endpoints directly from the docs
  • Consistency – All endpoints follow the same documentation structure
  • Reduced maintenance – Updates to the API spec automatically update the docs

Technical Implementation​

Key Improvements Made​

  1. Clear Getting Started Guide
  • Added step-by-step authentication instructions
  • Included practical cURL examples for immediate testing
  • Added comprehensive troubleshooting section
  • Provided transition sentences for better flow
  1. Standardized Endpoint Documentation
  • Shortened endpoint titles for better navigation (e.g., "Retrieve All Wallets" vs. "Retrieve a list of all multicurrency wallets...")
  • Expanded descriptions with use cases and context
  • Documented all error responses with explanations
  • Added best practices sections
  1. Enhanced Developer Experience
  • Hyperlinked technical terms for easier learning
  • Added response field explanations
  • Included multiple request examples (single/batch operations)
  • Provided copy-paste ready cURL commands

Challenges Faced & Solutions​

Challenge 1: OpenAPI Plugin Integration

Integrating the OpenAPI plugin with Docusaurus required understanding plugin configuration and theme customization.

Solution: Configured the plugin properly in docusaurus.config.js and mapped OpenAPI endpoints to documentation routes.

Challenge 2: Build Errors

Encountered npm run build failures due to plugin incompatibility with Docusaurus themes.

Solution: Added the following configuration to resolve the issue:

presets: [
  [
    'classic',
    {
      docs: {
        // ... other config
        docItemComponent: "@theme/ApiItem"
      }
    }
  ]
]

Challenge 3: Authentication Documentation

Documenting API authentication clearly for developers with varying experience levels.

Solution: Created a dedicated authentication section with visual examples, header format specifications, and a troubleshooting guide for common auth errors.

Key Learnings​

Technical Skills​

  • OpenAPI Specification – Understanding how to structure API definitions using OpenAPI 3.0
  • Docs-as-Code Workflow – Managing documentation alongside code using Git and CI/CD
  • Docusaurus Customization – Configuring plugins and themes for API documentation
  • API Documentation Best Practices – Balancing technical accuracy with readability

Documentation Principles​

  • Context Matters – Short endpoint titles with expanded descriptions improve navigation
  • Error Documentation – Documenting failures is as important as documenting success
  • Progressive Disclosure – Start simple (Getting Started) then dive deep (API Reference)
  • Developer Empathy – Anticipate questions and provide answers proactively

Automation Benefits​

  • OpenAPI automation reduces manual documentation work and keeps content synchronized
  • Interactive documentation allows developers to test without leaving the docs
  • Standardized structure ensures consistency across all endpoints

Reflection​

This project provided valuable hands-on experience with modern API documentation practices. I learned that effective API documentation is more than just listing endpoints—it requires understanding the developer journey, from initial authentication to handling edge cases.

Key insights:

1. Documentation is a product feature

Well-crafted documentation directly impacts developer adoption. Clear examples, comprehensive error handling, and practical use cases reduce friction and accelerate integration.

2. Automation enables quality

Using OpenAPI for documentation generation ensures consistency and reduces manual errors. When the API changes, the documentation updates automatically, maintaining accuracy.

3. Context improves comprehension

Adding transition sentences, use case examples, and best practices transforms documentation from a reference manual into a learning resource. Developers don't just want to know what an endpoint does—they want to know why and when to use it.

4. Troubleshooting documentation builds trust

Including common errors and solutions demonstrates understanding of real-world usage. It shows developers you've anticipated their challenges and provided solutions proactively.

This project reinforced that technical writing is about serving the reader's needs, not just documenting features. Every design decision—from endpoint title length to error response explanations—should prioritize developer experience.