Skip to main content

OpenAPI Management Guidelines

This document provides conventions and best practices for managing OpenAPI specifications in the ProvLabs documentation system.

Architecture Overview​

File Flow​

  1. Proto files in git submodules (extsource/provenance/, extsource/cosmossdk/)
  2. Generated OpenAPI files in temporary locations
  3. Unified specifications in config/ directory
  4. Split specifications in openapi/ directory (not committed)
  5. Served by Redocusaurus plugin at /api and /node routes

Directory Structure​

config/
├── provenance.openapi.yaml    # Unified API spec
├── noderpc.openapi.yaml       # Node RPC spec
├── base.schema.json           # Shared schemas
└── bv-apis.json              # DataRoom APIs

openapi/                       # Generated, not committed
├── openapi.yaml              # Split main spec
├── noderpc.openapi.yaml      # Node RPC copy
└── [various split files]     # Individual API specs

Protocol Buffer Integration​

Submodule Management​

  • Use sparse checkouts for proto directories only
  • Pin to specific release branches (e.g., release/v1.27.x)
  • Keep submodules updated with supported API versions
  • Document version compatibility in submodule README files

Code Generation​

# Standard pattern for proto processing
proto_dirs=$(find ./cosmos -path -prune -o -name '*.proto' -print0 | xargs -0 -n1 dirname | sort | uniq)
for dir in $proto_dirs; do
  query_file=$(find "${dir}" -maxdepth 1 \( -name 'query.proto' -o -name 'service.proto' \))
  if [[ ! -z "$query_file" ]]; then
    buf generate --template ../../openapiv3-template.yaml -o ../ "$query_file"
  fi
done

Template Configuration​

  • Use extsource/openapiv3-template.yaml for consistent generation
  • Configure buf to generate only query and service definitions
  • Exclude internal and deprecated APIs from generation

Schema Management​

Base Schema Handling​

  • Centralize common schemas in config/base.schema.json
  • Remove duplicate schemas to prevent conflicts during joins
  • Update references to point to centralized location

Schema Cleanup Process​

function removeBaseQuerySchemas() {
  SVC_FILE=$1

  # Remove duplicate schemas
  jq "del( \
        .components.schemas.\"cosmos.base.query.v1beta1.PageRequest\", \
        .components.schemas.\"cosmos.base.query.v1beta1.PageResponse\", \
        .components.schemas.\"cosmos.bank.v1beta1.Metadata\" \
        )" "$SVC_FILE" > "$SVC_FILE.tmp"

  mv "$SVC_FILE.tmp" "$SVC_FILE"

  # Update references to point to base schema
  sed -i '' -e "s|#/components/schemas/cosmos\.base\.query|../config/base.schema.json#/components/schemas/cosmos.base.query|g" "$SVC_FILE"
}

OpenAPI Specification Standards​

Specification Structure​

  • Follow OpenAPI 3.0+ specification
  • Include comprehensive operation descriptions
  • Provide example request/response bodies
  • Tag operations for logical grouping

Documentation Quality​

  • Write clear, concise operation summaries
  • Include parameter descriptions and constraints
  • Provide realistic example values
  • Document error responses and status codes

Tagging Strategy​

  • Use consistent tag naming across services
  • Group related operations under logical tags
  • Apply tags for proper navigation in documentation
  • Use x-tagGroups for organizing tag display

Redocly Integration​

Linting Standards​

# Lint all specifications before joining
redocly lint $openapi_specs
  • Configure Redocly rules in redocly.yaml
  • Enforce consistent naming conventions
  • Validate schema references and examples
  • Check for breaking changes in API updates

Joining Specifications​

# Join multiple specs into unified document
redocly join $openapi_specs --without-x-tag-groups -o config/provenance.openapi.yaml

Splitting for Documentation​

# Split unified spec for granular documentation
npx @redocly/cli@latest split config/provenance.openapi.yaml --outDir "$OPENAPI_DIR"

Version Management​

API Versioning​

  • Include version information in OpenAPI info block
  • Use semantic versioning for API specifications
  • Maintain backward compatibility when possible
  • Document breaking changes clearly

Release Process​

  • Generate specifications from tagged submodule versions
  • Test documentation generation with new specifications
  • Validate all examples and references
  • Update dependent documentation

Build Integration​

Automated Generation​

  • Run generation scripts as part of npm run prepare
  • Ensure idempotent script execution
  • Clean up intermediate files after processing
  • Fail builds on specification validation errors

Development Workflow​

# Local development cycle
npm run prepare          # Generate latest specs
npm start               # Start dev server with hot reload
npm run build           # Test production build

Quality Assurance​

Testing Standards​

  • Validate generated specifications with Redocly
  • Test documentation rendering in Redocusaurus
  • Verify all internal references resolve correctly
  • Check external API compatibility

Performance Considerations​

  • Monitor specification file sizes
  • Optimize for fast documentation loading
  • Consider splitting large specifications
  • Use efficient reference patterns

Troubleshooting​

Common Issues​

  1. Missing schemas: Check base schema references and cleanup functions
  2. Build failures: Verify all required tools are installed and accessible
  3. Broken references: Validate file paths and schema locations
  4. Submodule issues: Ensure proper sparse checkout configuration

Debugging Process​

  1. Run scripts individually to isolate issues
  2. Check intermediate file generation
  3. Validate OpenAPI specifications with online tools
  4. Test documentation rendering locally

Best Practices​

Specification Design​

  • Keep operations focused and atomic
  • Use consistent parameter naming
  • Provide comprehensive error documentation
  • Include security considerations

Maintenance​

  • Regular updates to submodule versions
  • Periodic review of generated documentation
  • Monitor for deprecated API features
  • Update examples with current data patterns