• Background
• Getting Started
  • Prerequisites
  • Running the Project
• OpenAPI Specification
  • Published Documentation
  • Live-Reload Documentation
• Running via Docker
  • Build Stages
  • Available Commands
• Contributing

This is a microservice project template for Python. It is intended to demonstrate a production-grade microservice in Python with a maintainable structure, optimised containerisation, build automation and a CI/CD pipeline. The project is using FastAPI which is a modern, fast (high-performance), web framework for building APIs with standard Python type hints.

The project focus on maintainability and testability. It is built with Poetry, linted with Flake8, and formatted with Black to ensure code quality and consistency.

The automation tool of choice for this project is Make, which provides a simple and cross-platform way to run common tasks such as installing dependencies, building the project, running tests, etc. This is coupled with an advanced multistage docker build to ensure the project can be completely built and run in an isolated deployment environment in a consistent manner.

• Python: The project is built with Python 3.11.
• Poetry: The dependency management tool of choice for this project.
• Docker: For containerisation support, so it can be completely built and run in an isolated environment.
• Make: For running common tasks such as installing dependencies, building the project, running tests, etc.

1. Clone the repository:

   git clone https://github.com/u-ways/fastapi-microservice-py.git

2. At the root of the project, build the project:

   make install-dependencies
   make build-app

3. Run the project:

    make run-app

At the end of a successful CI/CD pipeline, the OpenAPI documentation is published to GitHub Pages. You can access the documentation via the following link: https://u-ways.github.io/fastapi-microservice-py/

The FastAPI framework provides a great self-documenting feature that automatically generates an OpenAPI compliant documentation for your API endpoints, by default, two documentation interfaces are available:

• Swagger UI: http://0.0.0.0:8000/docs
• ReDoc: http://0.0.0.0:8000/redoc

You can also access the JSON schema of the OpenAPI documentation via:

curl -s http://0.0.0.0:8000/openapi.json | jq

To learn more about how you can extend the generated OpenAPI documentation, you can check the official guide here: FastAPI - Learn - How To - Recipes - Extending OpenAPI.

You can also run the project using Docker. Our Dockerfile is a multi-stage build based on the official slimmed down Python image. It's divided into the following stages:

This enables you to build and run the project in an isolated environment with all the dependencies and configurations bundled together without diverging image builds when you switch between development and production environments.

To test the Docker build, you can run the following commands:

make test-app-docker

To build and run the project in a development environment:

make run-app-docker-dev

To build and run the project in a production environment:

make run-app-docker-prod

Although this is more of an educational/demo project, I am open to contributions. If you have any suggestions or improvements, feel free to open a PR or an issue. The build and development process has been made to be as seamless as possible, so you can easily run and test your changes locally before submitting a PR.

On top of that, the CI/CD pipeline is configured to run the tests, formater and linter on every PR, so you can be sure that your changes are in line with the project standards. You can also run our code quality checks locally by running:

make check-code-quality

You can also run the linting and formatting actions to resolve any issues:

make format-code && make lint-code

Also, don't forget to set your IDE to run the tests using the pytest configuration. This will ensure that you can run the tests directly from your IDE and get immediate feedback on your changes. If you're using PyCharm, you can follow the instructions here.