Run Swagger UI so visitors can explore our APIs

[cclauss]

Many people would like to have better, more interactive documentation on Open Library APIs.

• https://openlibrary.org/developers/api
• https://github.com/internetarchive/openlibrary/wiki/Endpoints

Describe the problem that you'd like solved

Run https://github.com/swagger-api/swagger-ui on an Open Library server so that visitors can better understand and try out our APIs. #5898 could generate the required openapi.json file so our Swagger UI was kept up-to-date as our APIs change. The try it out feature can make our APIs come alive even for nontechnical visitors.

• Read https://swagger.io/tools/swagger-ui/ and https://github.com/swagger-api/swagger-ui
• Recommend how we could/should run swagger-ui on OL infrastructure.
• Get swagger-ui running using the openapi.json to drive the user experience.
  • --> https://github.com/internetarchive/openlibrary-api
  • --> https://internetarchive.github.io/openlibrary-api
• Demo on a weekly community call.
• List the Open Library APIs that are still missing.
• Update our Open Library API docs to be in sync with our swagger-ui server.
• Recommend what maintenance will be required of this new server.
  • Q: How do we update to a new version of swagger-ui ? -- This is done automatically by a GItHub Action.
  • Q: How do we update to a new version of swagger.yaml?
  • Q: How can we do analytics of how many unique visitors come to the site (per hour/day/week/month/year)?

Proposal & Constraints

Additional context

Stakeholders

[cclauss]

@RayBB @jimman2003 Would one of you be willing to lead this effort?

[RayBB]

@cclauss what exactly needs to be checked here?

[cclauss]

I added a todo list above.

[Dnouv]

@cclauss I would like to contribute to this issue, please let me know if it's still available or not?

[cclauss]

That would be great!! I discussed this briefly with @cdrini and he said that the best would be if we could take the JavaScript and CSS bits and host the Swagger UI page on our own web server. Here is an effort to do that with FastAPI:
https://fastapi.tiangolo.com/advanced/extending-openapi/#self-hosting-javascript-and-css-for-docs

[Dnouv]

Thank you! I will go through the FastAPI docs.

[Dnouv]

@cclauss, I'm trying to access the API page on the development version, but it returns 404, so where and how can I access the API page on the dev version or, more specifically, the route of /developer/API page in the repo? Could you please help me out with this?
Thank you!

[cclauss]

https://openlibrary.org/developers -- log in and click the Edit button in the upper right of the page.
https://openlibrary.org/developers/api -- log in and click the Edit button in the upper right of the page.

[Dnouv]

Thank you so much, @cclauss, for clearing my questions. So, if I got it correct, there is no template defined for the /developers/api page, and we need to create one template that integrates the Swagger-UI.
And I looked at the steps of adding/integrating the SwaggerUI in the OL, and it requires a few JS files.

swagger-ui.css
swagger-ui-bundle.js
swagger-ui-standalone-preset.js

So, this JS files should be added in openlibrary/plugins/openlibrary/js or do we prefer adding swagger-ui npm package?

Please correct me if I missed something.

[cclauss]

You will need to work with @jimchamp or @cdrini or others on that because I know Python but not all that JS/CSS stuff.

[Dnouv]

Thank you so much, @cclauss, for clearing my questions. So, if I got it correct, there is no template defined for the /developers/api page, and we need to create one template that integrates the Swagger-UI. And I looked at the steps of adding/integrating the SwaggerUI in the OL, and it requires a few JS files.

swagger-ui.css
swagger-ui-bundle.js
swagger-ui-standalone-preset.js

So, this JS files should be added in openlibrary/plugins/openlibrary/js or do we prefer adding swagger-ui npm package?

Please correct me if I missed something.

@cdrini or @jimchamp, could you please help me with a few questions.
Thank you!

[Dnouv]

@cclauss cdrini and jimchamp were busy, so I went ahead and used Unpkg in place of js files or npm module, I tried integrating the Swagger UI with the openapi.json, provided in the task list above; here is a pic of the page,

Feedbacks are most welcomed. Thank you!

[Dnouv]

@cclauss, I'm trying to commit the changes, but there is an unknown error, could you please help me out with this

gitpod /workspace/openlibrary $ git commit -m "Add swagger html and openapi"
`pre-commit` not found.  Did you forget to activate your virtualenv?

[jimman2003]

Hey, so openlibrary uses pre-commit , a python program to run some checks over the code, please install it through the pip package installer with: pip install pre-commit

[Dnouv]

Thank you so much for the help @jimman2003, I tried installing pre-commit but there was a new error

gitpod /workspace/openlibrary $ pip install pre-commit
pyenv: version `3.9.4' is not installed (set by /workspace/openlibrary/.python-version)

[jimman2003]

let me test also through gitpod :)

[Dnouv]

@jimman2003, thank you for your help! I resolved the issue.

[jimman2003]

Out of curiosity, how @Dnouv ?

[Dnouv]

I got it fixed after a few installations,

pyenv install 3.9.4
##Fixed pyenv: version `3.9.4' is not installed (set by /workspace/openlibrary/.python-version)

##Then your mentioned command
pip install pre-commit

And the changes got committed.
Once again, thank you!

[Dnouv]

@cclauss, could you please let me know the further tasks? I've opened a PR integrating Swagger UI and am still awaiting a review.
Feel free to comment. Thank you!