search

tlsnotary / docs-mdbook

TLSNotary Documentation created with mdBook
https://docs.tlsnotary.org
5 stars 11 forks source link

Render notary server openapi spec visually #77

Closed waddaboo closed 7 months ago

waddaboo commented 7 months ago

Reference issue: github-tlsnotary/tlsn#442

Additional notes:

yuroitaki commented 7 months ago

Reference issue: github-tlsnotary/tlsn#442

Additional notes:

  • Currently the link for API Endpoints is still using htmlpreview. It is possible to change to direct link to the swagger html but it requires further testing once the page is published.
  • htmlpreview sometimes requires to refresh manually in order to load.

Does this mean that direct link to the swagger html is not possible when deployed locally?

waddaboo commented 7 months ago

Not a frontend engineer here, but is it not possible to not store those swagger ui related js/css files locally but to call them from swagger CDN?

There's a few ways of doing this, can either use npm, docker, unpkg or static html. Reference here.

Does this mean that direct link to the swagger html is not possible when deployed locally?

It should be possible once the html is deployed since this repo is using github pages. Though I have yet to test it out myself as it requires the html file to be deployed first in order for it to work.

Alternatively, there's also a method to turn openapi.yaml files into markdown files by using swagger-markdown. The outcome would be something like this.

yuroitaki commented 7 months ago

There's a few ways of doing this, can either use npm, docker, unpkg or static html. Reference here.

I see, from a brief glance it seems like unpkg ll do the job, what do you think?

It should be possible once the html is deployed since this repo is using github pages. Though I have yet to test it out myself as it requires the html file to be deployed first in order for it to work.

I see, is there any way to setup a simple free website (e.g. using github.io) and test the deployment via github pages? Ideally we don't wanna risk breaking the production page since we don't have staging or dev environment to test this deployment.

Alternatively, there's also a method to turn openapi.yaml files into markdown files by using swagger-markdown. The outcome would be something like this.

Ah thanks for the suggestion — but I think I still prefer swagger UI than markdown 😆

waddaboo commented 7 months ago

Noted, will try to implement the suggested changes and make a new pr when its ready.