Edit

API Documentation

This page covers standards for documenting APIs using OpenAPI specifications across all Decentraland services.

Goals

Our API documentation approach ensures:

  • Standardization - Consistent OpenAPI specs across all services

  • Automation - Validation, bundling, and deployment via GitHub Actions

  • Centralization - All service documentation published through GitBook

  • Ownership - Documentation lives with each service repository

  • Accessibility - Contributor-friendly, up-to-date API references

Repository Structure

Each service repository MUST include a /docs directory with the following structure:

/docs
  openapi.yaml        # Source of truth (OpenAPI 3.1)
  openapi.json        # Auto-generated in CI for Hugo/renderers
  index.html          # Auto-generated standalone docs (optional)

File Requirements

openapi.yaml

  • MUST be the canonical source file

  • MUST use OpenAPI 3.1 specification

  • MAY have a service-identifying prefix (e.g., worlds-openapi.yaml)

  • MAY split into components/ or examples/ directories if needed

openapi.json

  • Auto-generated during CI/CD

  • Used by Hugo and other renderers

  • Do not edit manually

index.html

  • Auto-generated standalone documentation

  • Built using Redocly

  • Deployed to GitHub Pages

OpenAPI Standards

When writing openapi.yaml, follow these conventions to ensure consistency and clarity.

Endpoint Summary

MUST reflect the actual endpoint path:

Operation ID

MUST include the service name for global uniqueness:

Naming convention: {serviceName}_{operationDescription}

  • Use camelCase

  • Be descriptive but concise

  • Include HTTP method context when helpful (e.g., createUser, deleteParcel)

Versioning

MUST use semantic versioning (MAJOR.MINOR.PATCH) in info.version:

Version bumping rules:

  • MAJOR: Breaking changes (incompatible API changes)

  • MINOR: New functionality (backward-compatible)

  • PATCH: Bug fixes (backward-compatible)

Tags and Grouping

MUST use tags to group related endpoints:

Operations are grouped by tag in GitBook's navigation. Group related endpoints under the same tag for better organization.

Complete Example

Local Development

Preview Documentation Locally

Use Redocly CLI to preview your OpenAPI documentation:

Add to package.json

Add a build script for convenience:

Install Redocly CLI

Validate OpenAPI Spec

Automation Setup

Step 1: Configure GitBook Secrets

To publish API specs to GitBook, add these secrets to your repository:

Settings → Secrets and variables → Actions → New repository secret

Secret Name
Description
Where to Find

GITBOOK_ORGANIZATION_ID

Your GitBook organization ID

GitBook Settings → Organization

GITBOOK_TOKEN

GitBook API token

GitBook Settings → API Tokens

These secrets MUST be configured for the automated workflow to publish to GitBook.

Step 2: Add GitHub Actions Workflow

Create .github/workflows/build-api-docs.yml in your repository:

Parameters:

  • api-spec-file: Path to your OpenAPI spec (usually docs/openapi.yaml)

  • output-file: Where to generate HTML docs

  • output-directory: Directory for output files

  • api-spec-name: Unique name for your API spec (used in GitBook)

  • node-version: Node.js version to use

This workflow will:

  1. ✅ Validate the OpenAPI spec

  2. ✅ Bundle the spec into a single file

  3. ✅ Build static HTML documentation using Redocly

  4. ✅ Deploy automatically to GitHub Pages

  5. ✅ Publish spec to GitBook (if secrets are configured)

Step 3: Enable GitHub Pages

Configure GitHub Pages in your repository:

  1. Go to Settings → Pages

  2. Under Build and deployment:

    • Set Source to GitHub Actions

  3. Ensure there is an environment named github-pages

  4. Save settings

After the first successful workflow run, your documentation will be available at:

  • HTML Docs: https://decentraland.github.io/<repo>/index.html

  • OpenAPI Spec: https://decentraland.github.io/<repo>/openapi.yaml

  • Bundled JSON: https://decentraland.github.io/<repo>/openapi.json

These URLs remain valid as long as the repository exists and GitHub Pages is enabled.

Adding to GitBook

Once your API documentation is deployed, add it to the centralized GitBook documentation.

Manual Addition (Current Process)

  1. Navigate to the GitBook space

  2. Go to the API Reference section

  3. Click Add API Reference

  4. Enter your service details:

    • Name: Your service name (e.g., "Social Service")

    • OpenAPI URL: https://decentraland.github.io/{repo-name}/openapi.yaml

  5. Save

GitBook Integration Features

GitBook will automatically:

  • Parse your OpenAPI spec

  • Generate interactive API documentation

  • Create endpoint navigation based on tags

  • Provide "Try it" functionality

  • Keep docs in sync when you update the spec

Complete Setup Flow

Initial Setup

Ongoing Updates

Best Practices

Documentation Quality

  • Be descriptive: Write clear summaries and descriptions

  • Provide examples: Include request/response examples

  • Document errors: Describe all possible error responses

  • Use components: Reuse schemas via $ref to avoid duplication

  • Add descriptions: Every parameter, property, and response should have a description

Example with Best Practices

Schema Reusability

Security Schemas

Validation and Quality Checks

Pre-Commit Validation

Add a pre-commit hook or CI check:

Common Validation Rules

  • All paths have operation IDs

  • All operations have tags

  • All parameters have descriptions

  • All responses are documented

  • Examples are provided

  • Schemas are properly referenced

Troubleshooting

Workflow Fails

Problem: GitHub Actions workflow fails

Solutions:

  • Check workflow logs for validation errors

  • Run redocly lint docs/openapi.yaml locally

  • Verify file paths in workflow configuration

  • Ensure secrets are properly configured

GitHub Pages Not Working

Problem: Docs not appearing at GitHub Pages URL

Solutions:

  • Verify GitHub Pages is enabled in repository settings

  • Check that workflow completed successfully

  • Wait a few minutes for GitHub Pages to update

  • Verify the github-pages environment exists

GitBook Not Syncing

Problem: GitBook not showing updated API docs

Solutions:

  • Verify GitBook secrets are correct

  • Check that the OpenAPI URL is accessible

  • Manually trigger a refresh in GitBook

  • Verify OpenAPI spec is valid

Migration from Existing Docs

If you have existing API documentation:

  1. Export to OpenAPI: Convert existing docs to OpenAPI 3.1 format

  2. Validate: Use redocly lint to ensure compliance

  3. Add workflow: Set up GitHub Actions automation

  4. Test: Verify docs build and deploy correctly

  5. Update links: Point old documentation links to new GitHub Pages URL

  6. Archive old docs: Keep old docs for reference during transition

Next Steps

Resources

PreviousOverviewNextTesting Standards

Last updated