This repo demonstrates how "OpenAPI Driven Development". What I call using OpenAPI as a form of guardrail. My goal is to show how:
- Generating OpenAPI from code can help avoid "doc drift". The uneasy case when the docs differ than what the backend does.
- How including the OpenAPI schema inside can be a form of "checks and balances". Automated checks can verify that API changes are backward compatible.
- Finally, we can cut down the toil with automated publishing of OpenAPI artifacts like pydantic models and typescript clients.
pyproject.toml
the version here is the version for the service and our OpenAPI schema. We choose CalVer but alternative schemes are doable. The intent is to mark changes to the API clearly.bin/openapi
this is a simple bash script withtest
,update
, andpackages
commands. The script is used byMakefile
and.gitlab-ci-yaml
as examples of how to setup a convenient experience for the developer. e.g.bin/openapi update
updates youropenapi/schema.yaml
andbin/openapi test compatibility
will check againstmain
(the master branch of the repo) if there have been backward incompatible changes in your changes.packages/books_pydantic/package.json
andpackages/typescript_client/package.json
both are examples of how a "package" can be added easily by ensuring you have apackage.json
withupdate
,setup
, andpublish
scripts. Thebin/openapi packages
hooks into these!books
is an example (very contrite) FastAPI service.