How to insert markdowns in your FastAPI documentation

Sometimes only the Swagger documentation with the routes is not enough for the customers/clients, and the back-end should describe better the modules of the project. This article solve it, where a .md file will be loaded in our FastAPI application.

How do I start the FastAPI application ?

I had written an article where I teach you how to start your application, it is reachable at the following link: https://medium.com/@caetanoog/start-your-first-fastapi-server-with-poetry-in-10-minutes-fef90e9604d9.

Since you’ve already started your application, you can set your FastAPI instance as follow:

from fastapi import FastAPI
app = FastAPI(
    title="Project Name",
    description=""
)
@app.get("/") 
async def main_route():     
  return {"message": "Hey, It is me Goku"}

Note: Reserve the description field, because this is the place where the magic will happen.

Documentation

Now the project should have a docs folder, it should be created inside your principal folder, but inside this docs folder a folder called markdowns should be created too. Below the tree is shown, please create all the files too:

project_folder:
     - docs
          - markdowns
              - project_docs.md
          - export_project_docs.py

Markdown file

Your markdown should contains your project data, e.g: your modules descriptions or your diagrams (images).

Note: If you’d like to add images to this markdowns files, you’ll need to serve your own images, for it you can use FileResponse, if you still have questions, please write a comment and I can write another article teaching it.

#project_docs.md
...
Lorem ipsum dolor sit amet. Ut modi maiores vel itaque mollitia eos doloremque quaerat sed illum voluptatem id temporibus vitae est modi ullam hic internos quia. Quo quidem optio qui autem porro ut provident facilis qui placeat corrupti ut tempore omnis. Sit sequi fugiat qui magnam tenetur id doloremque iure qui accusamus maiores. Et iste unde hic facilis praesentium hic rerum galisum. Aut itaque iste sed quam dolorem et odio perferendis non voluptatum numquam ut galisum voluptates aut sapiente praesentium.
...

Since we have our .md file done, a class to export it as a text should be created, for it you can follow the example below:

#export_project_docs.py
class ProjectMarkDownsExporter:
   def __init__(self):
      self.base_docs_path = f"{__file__.replace('export_project_docs.py', '')}markdowns/project_docs.md"
def export_md_files_as_text(self):
   with open(self.base_docs_path, 'r') as file:
       markdown_text = file.read()
   return markdown_text
markdown_exporter = ProjectMarkDownsExporter()

Import the file in our FastAPI instance

The last thing that we need to do here is to import our created singleton instance and everything is done and your documentation will be placed in your Swagger :)

...
app = FastAPI(
    title="Project Name",
    description=markdown_exporter.export_md_files_as_text()
)
...

Conclusion

I hope you enjoyed the article, if you have any question, please write it in the comments, hope to see you in the next one.