Add OpenApi UI structure in docs folder for future use

[emostov]

This PR adds an OpenApi UI that will be hosted by github pages. The plans for v1.0.0 release are reflected in openapi-v1.yaml, while the plans for routes to add in v1.1.0 are reflected in openapi-v1-todo.yaml. The UI is currently set to show the v1.0.0 paths, which are not yet fully implemented.

Relates to #227

[danforbes]

How are you testing this? I don't know much about hosting stuff like this through GitHub Pages. My first inclination was to pull the branch down locally and try to access the UI that way but I realized that's not how things are set up.

[emostov]

@danforbes You should be able to pull the branch down and test it that way. Its in docs/dist/index.html. You will need to run yarn build:docs if you make any changes. For now I am more looking for feedback on the setup of the UI components and not the exact api specs since some still might change given the open PRs.

Also you can access the version from this branch here: https://paritytech.github.io/substrate-api-sidecar/dist/

[danforbes]

I think the directory structure and everything looks fine. I would suggest maybe adding a better README to the docs folder to explain where the actual OpenAPI spec is and what the other folders are for. Anything else in particular you were curious about?

[dvdplm]

Not all calls have error descriptions – does that mean they can't fail? In general this lgtm a part from a few nits.

[emostov]

Not all calls have error descriptions – does that mean they can't fail? In general this lgtm a part from a few nits.

In theory we only have to detail all known errors. So essentially all 4xx errors should be detailed and some 5xx that are hard coded. I actually have not gone through the code and the specs though to make sure they align. I mostly just have errors from middleware that apply broadly. If we want to be thorough this definitely needs to be looked at carefully.

[joepetrowski]

Confusing

[dvdplm]

In theory we only have to detail all known errors. So essentially all 4xx errors should be detailed and some 5xx that are hard coded. I actually have not gone through the code and the specs though to make sure they align. I mostly just have errors from middleware that apply broadly. If we want to be thorough this definitely needs to be looked at carefully.

It's ok to defer this to a separate PR. Can you file a ticket?

[dvdplm]

lgtm