Add SwaggerAPI docs to the Mkdocs site

[hulohot]

Feature Description

In order to have all of the information in the same place, it is a requirement that the Swagger API docs are also hosted on the documentation site.

Proposed Solution

Add the SwaggerAPI docs to this site, https://hulohot.github.io/dev-scoreboard/ under an API tab.

Benefits

Singular repository for documentation.

Possible Drawbacks

Difficulty of implementation

Additional Details

This will require that the FastAPI is also hosted.

[hulohot]

Here are the steps to serve Swagger API docs from FastAPI on your MkDocs documentation:

Install the necessary libraries:

pip install mkdocs mkdocs-material mkdocs-material-extensions fastapi uvicorn

Create a FastAPI app and define your API routes:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/")
async def read_users():
    return [{"username": "alice"}, {"username": "bob"}]

Generate the Swagger JSON file by running the following command:

uvicorn app:app --host 0.0.0.0 --port 8000 --workers 1 --proxy-headers --log-level warning --openapi-json openapi.json

This will start the FastAPI app and generate the Swagger JSON file at http://localhost:8000/openapi.json.

In your MkDocs configuration file (mkdocs.yml), add the following lines to the nav section:

nav:
  - Home: index.md
  - API: http://localhost:8000/docs

This will add a link to your API documentation to your navigation bar.

Add the following lines to the extra section of your MkDocs configuration file:

extra:
  openapi_url: http://localhost:8000/openapi.json
  swagger_ui_prefix: "swagger-ui"

This will tell MkDocs where to find the Swagger JSON file and what to name the Swagger UI directory.

Install the mkdocs-swagger-ui plugin by running the following command:

pip install mkdocs-swagger-ui

Add the swagger_ui plugin to the plugins section of your MkDocs configuration file:

plugins:
  - search
  - swagger_ui:
      openapi_url: $extra.openapi_url
      swagger_ui_prefix: $extra.swagger_ui_prefix

This will add the swagger_ui plugin to MkDocs and configure it to use the values defined in the extra section.

Start your MkDocs server by running the following command:

mkdocs serve

This will start your MkDocs server at http://localhost:8000/.

[hulohot]

I am having issues installing the swagger_ui, I'm going to move on from this at the current moment and come back.