Automated API documentation

[agraebe]

Status quo We have multiple API docs for RPC endpoints - all of which are managed manually and by different individuals:

• https://github.com/blockstack/stacks-blockchain/blob/master/docs/rpc-endpoints.md - @kantai
• https://github.com/blockstack/stacks-blockchain-api/blob/master/docs/openapi.yaml - @zone117x
• https://docs.blockstack.org/understand-stacks/stacks-blockchain-api - @agraebe
• Postman collection - @agraebe

The current state is resulting in inconsistencies - maybe there is a better way?

Proposal We could do the following:

• Use an OpenAPI spec inside this repo to document RPC endpoints
• Use the $ref feature inside the API repo to pull in RPC endpoint docs. The other endpoints will be documented as previously
• The docs could use the OpenAPI spec in this repo to generate a markdown snippet that would replace the list of RPC endpoints in the doc
• The API repo could automatically generate a new Postman Collection based on the OpenAPI spec

With this solution, we have only one source of truth for RPC docs and one source of truth for all API docs. Thoughts?

[diwakergupta]

To be clear, this only impacts the proxied v2/* endpoints, not all RPC endpoints, right?

[agraebe]

yes - the ones we documented already, but manually

[zone117x]

• openapi-to-postman looks good.
• openapi-generator to get markdown for docs seems like an easy win.
• Pulling in OpenAPI schema from the stacks-blockchain repo should be doable, might not be as simple as $ref but still seems pretty easy. The main concern here is versioning. Right now, the API would probably need to pin the external OpenAPI file to a specific commit hash, because the stacks-node and API repos are not always in perfect sync in regards to the APIs being used.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically closed. Please reopen if needed.

[blockstack-devops]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.