functional-typescript
functional-typescript copied to clipboard
Add support for generating API docs
Given one or more FTS definitions and their respective HTTP endpoints, add support for generating Stripe-style API docs describing those REST endpoints. This should be possible given the strong JSON schema typing info we have for each FTS definition. It's possible that there's a project in the greater JSON schema landscape which does something similar to this already.
As a follow-up, the docs would ideally integrate with the client SDKs that would be generated by #9.
The ideal user flow for consumers would be for FTS to be hidden as an implementation detail where a consumer developer would just use the SDK and accompanying docs specific to their language and environment of choice.
Some resources which may be useful:
- https://docute.org
- https://github.com/lord/slate
- https://docs.gitbook.com/content-editing/pages-structure
- https://auth0.com/docs/api/management/v2
For the MVP of this feature, simpler is definitely better. Just aiming to describe the REST endpoints and their respective parameters and return values with some cURL or httpie examples would be solid.
This will be used directly by fin but may be useful to other developers interested in the FTS standard.
I've evolved my thinking a bit on this.
First solve #13 and then use the OpenAPI spec along with ReDoc to generate the API docs.
Example API Docs generated with FTS => Saasify.