How Are Canton Developers Managing API Documentation from the CLI?

As Canton applications increasingly interact with external services and APIs, keeping API documentation up to date can become challenging.

We’re looking into CLI tools for API documentation as a way to make this process easier to automate.

The workflow we’re considering is:

1. Define or maintain the API specification using OpenAPI.
2. Validate the specification as part of development.
3. Generate or update API documentation from the command line.
4. Include documentation checks in CI/CD.
5. Keep API changes synchronized with the application code.

This seems especially useful when a Canton application needs to communicate with external services through APIs. Instead of manually updating documentation after every API change, the documentation workflow could become part of the development pipeline.

I’m curious how other Canton developers are approaching this:

• Are you using a CLI tool to generate API documentation?
• How do you keep API documentation synchronized with your API implementation?
• Are OpenAPI specifications part of your Canton development workflow?
• Do you automate documentation updates through CI/CD?

I’d be interested to hear what tools and workflows the community is using.

You can check all tools and developer Infra being used by canton community at the official dev hub: http://dev-hub.canton.foundation/

We’ve seen ReadMe (https://readme.com/) used for this kind of workflow. Not currently using it ourselves, but it’s a good reference.

The general approach is to keep an OpenAPI specification (either maintained manually or generated from the code), validate it as part of development, synchronize the API reference with ReadMe, and run those steps in CI/CD so the documentation stays in sync with the implementation.

Some useful references:

• Documentation as Code / new CLI: The ReadMe CLI Tool · ReadMe
• ReadMe CLI: Syncing Docs via CLI / GitHub
• OpenAPI support: OpenAPI Support