Live API on SwaggerHub

[faboweb]

The idea is to have links to the API on SwaggerHhub that reflect the versions of the API definition on develop and master on GitHub.

SwaggerHub has such features, but we need to downgrade the specification from version 3 to version 2 of the OpenAPI spec.

See: https://app.swaggerhub.com/help/integrations/github-sync > Considerations

Reference: #383

[zramsay]

can we use Slate? it's what we're using for Tendermint

[faboweb]

Good idea to consolidate tools. Why did you choose Slate over OpenAPI though?

[zramsay]

no reason in particular. When I joined the company, Anton had just done: tendermint/tendermint#526 so when folks starting asking for RPC docs (tendermint/tendermint#691), sticking with Slate made the most sense.

[faboweb]

OpenAPI (Swagger) has the advantage, that you can directly use the queries against a node making it easy to play around or test the API.
If this is all too fancy to have, I am OK with consolidating tools and use Slate. Let's definitely choose one API documentation tool.

[faboweb]

Zach and I agreed to try to use Slate for all API documentation as Slate is already setup and integrates into the code.

[zramsay]

update: neither of us has used both sufficiently to judge the pros and cons ... so we're gonna run with both for the time being and re-evaluate in the future

[cwgoes]

Closing as this discussion no longer reflects the state of the SDK documentation - please continue discussion in #1020, #1460, or #2137.