Repository: internetarchive/openlibrary

Issue:
Run Swagger UI so visitors can explore our APIs
<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->

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
<!-- A clear and concise description of what you want to happen. -->
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](https://swagger.io/tools/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.

* [x] Read https://swagger.io/tools/swagger-ui/ and https://github.com/swagger-api/swagger-ui
* [x] Recommend how we could/should run `swagger-ui` on OL infrastructure.
* [x] Get `swagger-ui` running using the [`openapi.json`](https://github.com/internetarchive/openlibrary/pull/5898/files#diff-c8dc4c1e479f3120bf2834ed4be53988bc795a39ac548200295461b6837d78cb) 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](https://openlibrary.org/developers/api) that are still missing.
* [ ] Update our [Open Library API docs](https://openlibrary.org/developers/api) 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`](https://github.com/internetarchive/openlibrary-api/blob/main/swagger.yaml)?
    * Q: How can we do analytics of how many unique visitors come to the site (per hour/day/week/month/year)?

![Screenshot 2021-11-22 at 16 39 59](https://user-images.githubusercontent.com/3709715/142890924-2be77a61-c389-4385-a20f-9b543765d00c.png)

### Proposal & Constraints
<!-- What is the proposed solution / implementation? Is there a precedent of this approach succeeding elsewhere? -->

<!-- Which suggestions or requirements should be considered for how feature needs to appear or be implemented? -->

### Additional context
<!-- Add any other context or screenshots about the feature request here. -->

### Stakeholders
<!-- @ tag stakeholders of this bug -->





Discussion:
@RayBB @jimman2003 Would one of you be willing to lead this effort?
@cclauss what exactly needs to be checked here?
I added a todo list above.
@cclauss I would like to contribute to this issue, please let me know if it's still available or not?
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
Thank you! I will go through the FastAPI docs.

@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! 
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.
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](https://www.npmjs.com/package/swagger-ui)?

Please correct me if I missed something.
You will need to work with @jimchamp or @cdrini or others on that because I know Python but not all that JS/CSS stuff.
> 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](https://www.npmjs.com/package/swagger-ui)?
> 
> Please correct me if I missed something.

@cdrini or @jimchamp, could you please help me with a few questions.
Thank you!
@cclauss cdrini and jimchamp were busy, so I went ahead and used [Unpkg](https://unpkg.com/) 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,

<img width="824" alt="image" src="https://user-images.githubusercontent.com/61188295/147540638-55559822-137c-49a5-bf59-24a3880ef9ac.png">

Feedbacks are most welcomed. Thank you!
@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?
``` 
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
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)
``` 
let me test also through gitpod :)

Resolving patch:
diff --git a/openlibrary/plugins/openlibrary/code.py b/openlibrary/plugins/openlibrary/code.py
--- a/openlibrary/plugins/openlibrary/code.py
+++ b/openlibrary/plugins/openlibrary/code.py
@@ -1127,6 +1127,7 @@ def setup():
         design,
         status,
         authors,
+        swagger,
     )
 
     sentry.setup()
@@ -1138,6 +1139,7 @@ def setup():
     events.setup()
     status.setup()
     authors.setup()
+    swagger.setup()
 
     from openlibrary.plugins.openlibrary import api
 
diff --git a/openlibrary/plugins/openlibrary/swagger.py b/openlibrary/plugins/openlibrary/swagger.py
new file mode 100644
--- /dev/null
+++ b/openlibrary/plugins/openlibrary/swagger.py
@@ -0,0 +1,13 @@
+from infogami.utils import delegate
+from infogami.utils.view import render_template
+
+
+def setup():
+    pass
+
+
+class swagger(delegate.page):
+    path = "/swagger/docs"
+
+    def GET(self):
+        return render_template("swagger/swaggerui.html")


Test patch: