functional-typescript icon indicating copy to clipboard operation
functional-typescript copied to clipboard

Add support for generating API docs

Open transitive-bullshit opened this issue 5 years ago • 2 comments

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.

transitive-bullshit avatar Apr 08 '19 20:04 transitive-bullshit

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.

transitive-bullshit avatar May 01 '19 08:05 transitive-bullshit

Example API Docs generated with FTS => Saasify.

transitive-bullshit avatar Oct 28 '19 21:10 transitive-bullshit