Auto Update API Specs in Gitbook

[swidnikk]

Problem description

Presently the the api spec is manually uploaded to Gitbook. This means if the api changes in anyway, the documentation will drift and requires a manual update. It is not known how far the documentation has already drifted.

Gitbook has an "automatic api docs" feature which works by linking the published spec via URL or through Github actions,
https://www.gitbook.com/blog/new-in-gitbook-automatic-api-docs

However, cross-site security in Gitbook causes auto linking to fail as the docs site https://guardian.hedera.com/ cannot reference the published spec file from another domain.

Requirements

Implement Gitbook's "automatic api docs" feature by linking the published spec,
https://www.gitbook.com/blog/new-in-gitbook-automatic-api-docs

This can addressed in one of the following two ways

1. Updating the spec via Github actions
   https://gitbook.com/docs/api-references/guides/support-for-ci-cd-with-api-blocks#update-your-spec-with-github-actions

2. Allowing cross site access to the spec's URL
   https://gitbook.com/docs/api-references/openapi#why-isnt-my-spec-loading

Regardless of which option, linking to a live production spec (though MGS specific) would allow live testing by developers directly from Gitbook via Scalar,

• https://guardianservice.app/api-docs/
• https://gitbook.com/docs/api-references/openapi#test-it-powered-by-scalar

Definition of done

The spec is linked via URL or Github actions and docs auto update as described on the feature page below,
https://www.gitbook.com/blog/new-in-gitbook-automatic-api-docs

Acceptance criteria

1. Link spec url and reference an API endpoint on a Gitbook page
2. Change some aspect of the API via the swagger yml file (e.g. trivial parameter description for testing)
3. Inspect that the Gitbook page automatically reflects the update
4. (Optional / if linked to the live MGS api service / spec) Test out API directly via Gitbook

[swidnikk]

@Pyatakov @ihar-tsykala @dariy-rised @Neurone take a look and see what you think — is this ready to publish? There seem to be some malformed examples that require looking at more closely.

This is generated from the swagger.yaml upload and can also be configured to auto update. This way any api references in docs can link directly,

You can preview here,
https://dev.guardian.hedera.com/api-reference

It will publish like this (not live yet),