fastapi-code-generator: OpenAPI to FastAPI application generation

Generating a FastAPI application from an OpenAPI contract

fastapi-code-generator addresses a specific starting-point problem: turning an existing OpenAPI document into Python source for a FastAPI service. The intended users are Python developers and teams that already have an API contract but want generated request models, response models, and application or router files rather than creating that structure manually. The package is not limited to one output style. Its CLI can select Pydantic v2 base models, Pydantic v2 dataclasses, standard dataclasses, `TypedDict`, or `msgspec.Struct` through `--output-model-type`.

The default command writes to an output path supplied with `--output`. The repository includes a `swagger.yaml` file, but the README does not specify whether it is intended as a universal example, a test fixture, or a complete specification for the generated application. A reader should therefore provide their own OpenAPI file and inspect the resulting source rather than assuming that every generated endpoint is production-ready. The project metadata describes it as an application generator, not as a validator of the OpenAPI contract itself.

How OpenAPI input becomes generated FastAPI files

The documented dependency on `datamodel-code-generator` explains the central architecture. `fastapi-code-generator` handles the FastAPI-oriented output, while `datamodel-code-generator` supplies the model layer from OpenAPI schemas. The CLI passes the input document to the generation process, writes the requested output path, and can render application files through the project's templates. The README points to the overview guide for complete output examples, template details, custom visitors, and router generation, but it does not reproduce the complete internal module structure or the generated file tree.

The CLI exposes several points of control. `--model-file` selects an existing model-related input or output context, while `--template-dir` and `--model-template-dir` allow project-specific templates. `--custom-visitor` accepts a visitor file, indicating that schema processing can be extended beyond the defaults. `--use-annotated` changes how field constraints are represented, `--reuse-model` reuses identical generated models, and `--enum-field-as-literal` controls enum fields. These options affect code generation before the application is run, so they matter when generated output must match an established project style.

Routers are optional rather than implicit. Passing `--generate-routers` requests router modules, and `--specify-tags` can restrict regeneration to named tags. The README gives the example tags `Wild Boars, Fat Cats`, which demonstrates tag selection without claiming that those names belong to every OpenAPI document. A single-file output is available through the default command, while the modular router workflow requires `--template-dir modular_template` in the documented example.

Installing the CLI and generating the first application

The README gives two installation paths. `uv` provides a tool installation, while `pip` is the conventional Python package route. Both commands install the package and expose the `fastapi-codegen` command.

uv tool install fastapi-code-generator

For a `pip`-based environment, use:

pip install fastapi-code-generator

The shortest documented first generation passes an OpenAPI file and an output directory, and explicitly selects the default Pydantic v2 base-model representation.

fastapi-codegen --input openapi.yaml --output app --output-model-type pydantic_v2.BaseModel

The expected result is generated source under `app`. The README does not document a command for starting that application, so it would be a separate FastAPI deployment step rather than part of the documented generator flow. For a modular layout, the project shows this command:

fastapi-codegen --input openapi.yaml --output app --template-dir modular_template --generate-routers

That example is the appropriate starting point when the desired result is router modules instead of one generated file. The output path and template directory must match the directory structure already present in the project, because the README does not claim that the generator creates or selects those directories automatically.

Pydantic v2, Python versions, and generation controls

The package metadata requires Python `>=3.10`, and the CLI lists target versions `3.10`, `3.11`, `3.12`, `3.13`, and `3.14`. The project depends on `pydantic>=2.12,<3`, so its default model output is tied to the Pydantic v2 line. That makes the tool relevant to current FastAPI projects that already standardize on Pydantic v2, but it also creates a compatibility boundary for codebases that still need an older Pydantic generation target.

The output model is not limited to Pydantic classes. The documented choices are `pydantic_v2.BaseModel`, `pydantic_v2.dataclass`, `dataclasses.dataclass`, `typing.TypedDict`, and `msgspec.Struct`. This is useful when the surrounding project has a preferred validation or typing model, although the README does not provide a comparison of the generated runtime behavior among these choices. The CLI help confirms selection, not that every option has identical template support.

Constraint handling can be switched with `--use-annotated`. The `--strict-nullable` option makes generation respect explicit OpenAPI nullable flags. `--enable-faux-immutability` generates frozen Pydantic models whose instances are hashable when their fields are hashable. These switches are useful for code review because they change the generated class definition rather than merely formatting the output. They should be chosen based on the contract and the application model, then checked against the actual generated files.

Remote references, private networks, and security boundaries

OpenAPI documents can contain `$ref` targets that point outside the input file. The CLI exposes `--allow-remote-refs` and `--no-allow-remote-refs`, with the default described as following `datamodel-code-generator` compatibility behavior. The project also adds `--allow-private-network` for trusted remote references that resolve to local or private network addresses.

This is a meaningful operational boundary. Allowing remote references can make a local specification usable when it depends on shared schemas, but it also causes generation to fetch external targets. Blocking them makes generation more predictable in environments where network access is restricted or an input document is meant to be self-contained. The README does not document caching, timeout behavior, retry behavior, or a complete policy for untrusted references, so those details cannot be inferred from the CLI flags.

For private network targets, the separate opt-in flag should not be treated as harmless by default. The documented wording calls these targets trusted, which places the trust decision on the operator. A team using CI should inspect the exact generator invocation and decide whether remote references are required before enabling the relevant option.

Template and router customization for larger services

The project is more than a fixed one-file converter. `--template-dir` points to an application template set, `--model-template-dir` controls model templates, and `--custom-visitor` supplies a visitor for changing the generation process. The documentation site is identified as the source of truth for template details and custom visitors, but the README does not define template file names, context variables, or the visitor interface. A custom extension therefore cannot be implemented accurately from the README alone.

Router generation provides a second level of organization. `--generate-routers` enables router modules, while `--specify-tags` limits the operation set by tag. The documented modular command includes `--template-dir modular_template`, so this is not merely a flag attached to the default template. The README gives a tag-filtered example:

fastapi-codegen --input openapi.yaml --output app --template-dir modular_template --generate-routers --specify-tags "Wild Boars, Fat Cats"

The command demonstrates the syntax, not a contract for the tags in a particular API. Tag names that do not exist in the input will not produce useful routers, and the README does not describe behavior for missing tags or partial matches. The custom visitor option is similarly promising for existing code-generation rules, but its interface remains undocumented in the README. Those two gaps matter when a team expects the generator to fit a pre-existing modular layout.

Maintenance, licensing, and adoption trade-offs

The repository is not archived, and the last push was on 2026-10-12. The listed releases include `0.8.1` on 2026-07-01, `0.8.0` on 2026-06-26, and `0.7.0` on 2026-05-31. Those facts indicate repository activity and package releases, but they do not by themselves establish that every generator mode is stable. The package metadata labels the development status as `2 - Pre-Alpha`, which is a direct quality boundary for an adoption decision.

The project uses the MIT license. That permits use and modification under the license's terms, but organizations still need to review the license file and dependencies separately when distributing generated code or the tool. The repository does not claim that generated output is owned differently from ordinary generated source, nor does the README provide a policy for generated-code licensing.

Compared with writing FastAPI models and routes by hand, the generator reduces repetitive scaffolding and keeps initial structure aligned with an OpenAPI document. Compared with a full application framework or a code-generation pipeline built around a specific architecture, it leaves more project-specific decisions to the team. Its value is therefore concentrated in contract-to-scaffold work. The pre-alpha classification and the undocumented extension details are reasons to inspect output in code review rather than commit directly to an established source layout.

Editorial conclusion

Adopt fastapi-code-generator when the team needs a FastAPI scaffold from an OpenAPI file and can review the generated models and routes. Do not treat its output as a finished application without checking naming, custom templates, validation behavior, and remote reference policy. For projects requiring bespoke architecture or hand-written business behavior, verify those requirements against the generated `app` directory first.

Frequently asked questions

Official sources

1. Issues
2. koxudaxi/fastapi-code-generator on GitHub
3. License: MIT
4. README
5. Releases