From d7df6bdb15a095d7fdc18c7fae06c085b78662be Mon Sep 17 00:00:00 2001 From: Jeet Shah Date: Thu, 12 Nov 2026 17:17:42 +0530 Subject: [PATCH 1/5] fix: support PostgreSQL OpenAPI generation locally --- Makefile | 3 +++ README.md | 11 +++++++++++ config/local_postgres.py | 16 ++++++++++++++++ 3 files changed, 30 insertions(+) create mode 100644 config/local_postgres.py diff --git a/Makefile b/Makefile index 72ee1aeb8..b9db40b0b 100755 --- a/Makefile +++ b/Makefile @@ -59,6 +59,9 @@ shell: check-uv # Load a shell openapi-generate: check-uv uv run manage.py spectacular --color --file openapi.yml ${local_config} +openapi-generate-postgres: check-uv # Generate OpenAPI schema using the local PostgreSQL database + uv run manage.py spectacular --color --file openapi.yml --settings=config.local_postgres + docker-up: # (Docker) Create services/volumes/networks docker compose up -d diff --git a/README.md b/README.md index 8c1255ab7..495680d81 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,17 @@ make migrate Run `make help` to see all tasks. +When regenerating `openapi.yml`, use the PostgreSQL-backed settings to keep +database-derived integer bounds consistent with the checked-in schema: + +```sh +make openapi-generate-postgres +``` + +This expects a local PostgreSQL database. Set `POSTGRES_DB`, `POSTGRES_USER`, +`POSTGRES_PASSWORD`, `POSTGRES_HOST`, and `POSTGRES_PORT` to override the +defaults (`pokeapi`, `ash`, `pokemon`, `localhost`, and `5432`). + ## Docker and Compose   [![docker hub](https://img.shields.io/docker/v/pokeapi/pokeapi?label=tag&sort=semver)](https://hub.docker.com/r/pokeapi/pokeapi) There is also a multi-container setup, managed by [Docker Compose V2](https://docs.docker.com/compose/). This setup allows you to deploy a production-like environment, with separate containers for each service, and is recommended if you need to simply spin up PokéAPI. diff --git a/config/local_postgres.py b/config/local_postgres.py new file mode 100644 index 000000000..9b8ad6ac5 --- /dev/null +++ b/config/local_postgres.py @@ -0,0 +1,16 @@ +"""Local development settings for generating the schema against PostgreSQL.""" + +import os + +from .local import * # noqa: F403 + +DATABASES: dict[str, DatabaseSettings] = { # noqa: F405 + "default": { + "ENGINE": "django.db.backends.postgresql", + "NAME": os.environ.get("POSTGRES_DB", "pokeapi"), + "USER": os.environ.get("POSTGRES_USER", "ash"), + "PASSWORD": os.environ.get("POSTGRES_PASSWORD", "pokemon"), + "HOST": os.environ.get("POSTGRES_HOST", "localhost"), + "PORT": os.environ.get("POSTGRES_PORT", "5432"), + } +} From 9265747d88821a29748d25af1ad52aa49d981798 Mon Sep 17 00:00:00 2001 From: Jeet Shah Date: Thu, 12 Nov 2026 23:01:58 +0530 Subject: [PATCH 2/5] docs: explain OpenAPI generation without database --- CONTRIBUTING.md | 9 +++++++++ Makefile | 3 --- README.md | 11 ----------- config/local_postgres.py | 16 ---------------- 4 files changed, 9 insertions(+), 30 deletions(-) delete mode 100644 config/local_postgres.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fa06a642..1ae5e5e07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,15 @@ make format # or: uv run ruff format . make typecheck # or: uv run ty check ``` +The `generate-openapi` pre-commit hook regenerates `openapi.yml`. To run it manually, use: + +```bash +uv run manage.py spectacular --file openapi.yml --settings=config.docker_compose +``` + +This command does not need a running database: the configured database backend determines integer bounds in the +schema, and schema generation does not query the database. + > [!NOTE] > As of right now we are not strictly enforcing linting and typechecking, but we will be in the future. Please try to make sure your code passes these checks. diff --git a/Makefile b/Makefile index b9db40b0b..72ee1aeb8 100755 --- a/Makefile +++ b/Makefile @@ -59,9 +59,6 @@ shell: check-uv # Load a shell openapi-generate: check-uv uv run manage.py spectacular --color --file openapi.yml ${local_config} -openapi-generate-postgres: check-uv # Generate OpenAPI schema using the local PostgreSQL database - uv run manage.py spectacular --color --file openapi.yml --settings=config.local_postgres - docker-up: # (Docker) Create services/volumes/networks docker compose up -d diff --git a/README.md b/README.md index 495680d81..8c1255ab7 100644 --- a/README.md +++ b/README.md @@ -125,17 +125,6 @@ make migrate Run `make help` to see all tasks. -When regenerating `openapi.yml`, use the PostgreSQL-backed settings to keep -database-derived integer bounds consistent with the checked-in schema: - -```sh -make openapi-generate-postgres -``` - -This expects a local PostgreSQL database. Set `POSTGRES_DB`, `POSTGRES_USER`, -`POSTGRES_PASSWORD`, `POSTGRES_HOST`, and `POSTGRES_PORT` to override the -defaults (`pokeapi`, `ash`, `pokemon`, `localhost`, and `5432`). - ## Docker and Compose   [![docker hub](https://img.shields.io/docker/v/pokeapi/pokeapi?label=tag&sort=semver)](https://hub.docker.com/r/pokeapi/pokeapi) There is also a multi-container setup, managed by [Docker Compose V2](https://docs.docker.com/compose/). This setup allows you to deploy a production-like environment, with separate containers for each service, and is recommended if you need to simply spin up PokéAPI. diff --git a/config/local_postgres.py b/config/local_postgres.py deleted file mode 100644 index 9b8ad6ac5..000000000 --- a/config/local_postgres.py +++ /dev/null @@ -1,16 +0,0 @@ -"""Local development settings for generating the schema against PostgreSQL.""" - -import os - -from .local import * # noqa: F403 - -DATABASES: dict[str, DatabaseSettings] = { # noqa: F405 - "default": { - "ENGINE": "django.db.backends.postgresql", - "NAME": os.environ.get("POSTGRES_DB", "pokeapi"), - "USER": os.environ.get("POSTGRES_USER", "ash"), - "PASSWORD": os.environ.get("POSTGRES_PASSWORD", "pokemon"), - "HOST": os.environ.get("POSTGRES_HOST", "localhost"), - "PORT": os.environ.get("POSTGRES_PORT", "5432"), - } -} From 78d62e63ed78ddafa57b956352a2d1328fd4f69d Mon Sep 17 00:00:00 2001 From: Jeet Shah Date: Fri, 13 Nov 2026 13:20:46 +0530 Subject: [PATCH 3/5] docs: address OpenAPI generation review feedback --- CONTRIBUTING.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ae5e5e07..7ea368f1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,16 +26,9 @@ make format # or: uv run ruff format . make typecheck # or: uv run ty check ``` -The `generate-openapi` pre-commit hook regenerates `openapi.yml`. To run it manually, use: - -```bash -uv run manage.py spectacular --file openapi.yml --settings=config.docker_compose -``` - -This command does not need a running database: the configured database backend determines integer bounds in the -schema, and schema generation does not query the database. - > [!NOTE] +> The `generate-openapi` pre-commit hook uses the configured database backend to determine integer bounds without querying a running database; after model or schema changes, run pre-commit to regenerate `openapi.yml`, and run pre-commit locally before opening a pull request to catch CI failures early. +> > As of right now we are not strictly enforcing linting and typechecking, but we will be in the future. Please try to make sure your code passes these checks. - Commit your code and push it to GitHub From 393e027ceeed62dd7e6ac7138c4b4b4799dc7c49 Mon Sep 17 00:00:00 2001 From: Triyan Mukherjee Date: Fri, 13 Nov 2026 22:37:01 +0530 Subject: [PATCH 4/5] Revise contributing guidelines for pre-commit usage Updated instructions for running pre-commit hooks and clarified linting and typechecking enforcement. --- CONTRIBUTING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ea368f1e..30a019f5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,9 +27,7 @@ make typecheck # or: uv run ty check ``` > [!NOTE] -> The `generate-openapi` pre-commit hook uses the configured database backend to determine integer bounds without querying a running database; after model or schema changes, run pre-commit to regenerate `openapi.yml`, and run pre-commit locally before opening a pull request to catch CI failures early. -> -> As of right now we are not strictly enforcing linting and typechecking, but we will be in the future. Please try to make sure your code passes these checks. +> Run `pre-commit` locally before opening a pull request to catch CI failures early this handles formatting, linting, type checking, and regenerating `openapi.yml` after model or schema changes. If you don't have `pre-commit` set up, you can run the checks defined in `.pre-commit-config.yaml` manually. - Commit your code and push it to GitHub From 8731533a4330688eb00fbf74c3efaaaff7c92cab Mon Sep 17 00:00:00 2001 From: Jeet Shah Date: Sat, 14 Nov 2026 00:30:52 +0530 Subject: [PATCH 5/5] docs: clarify pre-commit guidance --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30a019f5e..674027649 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ make typecheck # or: uv run ty check ``` > [!NOTE] -> Run `pre-commit` locally before opening a pull request to catch CI failures early this handles formatting, linting, type checking, and regenerating `openapi.yml` after model or schema changes. If you don't have `pre-commit` set up, you can run the checks defined in `.pre-commit-config.yaml` manually. +> Run `pre-commit` locally before opening a pull request to catch CI failures early. It regenerates `openapi.yml` after model or schema changes. If you have not set up `pre-commit`, run the checks defined in `.pre-commit-config.yaml` manually. - Commit your code and push it to GitHub