Evolution of Service Documentation

Danang, 05.2024
CPaaS, Messaging team

Quickly about our team:

  • CPaaS Messaging: 3 developers and 1 QA
  • 20+ services
  • Singapore based
  • Main tech stack: .NET, Java, RabbitMQ, MSSQL

Past practice and challenges

A developer has implemented a new feature
There is no toolkit to conveniently update the OpenAPI specification
All related confluence pages have to be found and updated
All related Postman collections have to be updated
Many architectural decisions are not documented at all

Challenges:

  • The documentation is scattered across different locations
  • Typos or mistakes can easily slip through
  • Complexity leads to inconsistency

What makes documentation stand out?

Documentation
External
Internal
External

Customers

  • Quick start of using our services
  • Improved user experience
  • Consistency and accuracy
External

Product team

  • Documentation consistency
  • Clear picture of product capabilities
  • Easy collaboration across teams
  • Reduce maintainance overhead
External
Internal

Dev & QA

  • Streamlined documentaiton process
  • Minimum effort on maintainance
  • Easy collaboration between DEV and QA teams
  • Centralizing docs location
Internal

Operations team

  • Consistent API
  • Easier interaction with our services
Internal

How can we solve these problems?

OpenAPI specification

NSwag library

  • Open-source toolchain for .NET solutions
  • 6.5k stars on GitHub
  • Can generate OpenApi/Swagger specifications
  • Can generate C# and JS/TS clients based on the specification

Operation annotations:

Operation annotations:

Operations:

Example annotations:

Examples:

What can we do with this specification?

Backward-incompatible changes

Breaking changes:

Breaking changes:

Data Contract Change:

→

OpenAPI Comparator

  • Compare and report about changes in 2 OAS
  • Has ~50 rules to check
  • Available for commercial use

SDK Generation

After merging PR:

  1. We start an async Jenkins job that checks OAS changes
  2. If there are any changes:
    1. The job respectively generates a new SDK client
    2. Pushes it to AWS CodeArtifactory
    3. Updates the saved OAS with the new version

OpenAPI generator

  • 50+ output formats supported
  • Supports template customization
  • ~20k stars on GitHub

Generating SDKs:

→

Publishing SDKs:

Potential issues:

  • Some templates might require adjustment

Async API

  • Protocol-agnostic, supports AMQP, WebSockets, Kafka, HTTP, etc.
  • Has nice toolset to edit and view a specification
  • ~4k stars on GitHub

Code annotations:

Code annotations:

Code annotations:

Code annotations:

Schema viewer:

Events overview:

Potential issues:

  • Generator might not support polymorphic behavior

Cortex

  • Internal developer portal that aggregates all related information for the services
  • Has decent amount of integrations with external services
  • Already paid and used in 8x8

What's next?

  • Annotate all components with OAS and AsyncAPI attributes and enrich these specification with more examples
  • Finalize CI integration
  • Use Cortex more extensively aggregating ADRs and documentation links in one place

Q&A

Thanks