Spec Repo

A "spec repo" is a repository (or, more generally, a directory), that contains files necessary for apigentools to generate your client code. The layout is as follows:

├── .gitignore
├── config
│   ├── config.json                 # general config for apigentools
│   └── languages
│       └── java_v1.json            # openapi-generator config for Java client for v1 API
├── downstream-templates
│   └── java
│       └── LICENSE                 # a file/template to add to generated client
├── generated                       # generated code will end up in this directory
│   └── .gitkeep
├── spec
│   └── v1                          # directory with spec of v1 of the API
│       ├── accounts.yaml           # example: spec of the accounts API
│       ├── header.yaml             # header of the OpenAPI spec
│       └── shared.yaml             # entities shared between multiple parts of the OpenAPI spec
├── template-patches
│   └── java-01-minor-change.patch  # a patch to apply to openapi-generator template
└── templates                       # openapi-generator templates with applied patches end up here
    └── .gitkeep

You can create a basic scaffold of a spec repo using the init subcommand. For example:

apigentools init myspecrepo

Most of the paths in this layout can be overriden with command line arguments passed to the apigentools executable.

Overview of spec repo contents


This is a standard .gitignore file.


This is a directory containing config.json, which is a configuration file for apigentools.


This directory contains openapi-generator configuration files. There must be one file for every language and major API version configuration in your config/config.yaml. For information on what keys can go in these files, use openapi-generator config-help -g <LANGUAGE>.


This directory contains downstream templates (i.e. templates that are provided by the user, rather than openapi-generator. Place these templates in language specific directories, e.g. downstream-templates/java. Place files like top-level README.mds, top-level pom.xmls, etc., here.


This directory contains code generated by apigentools. It is usually empty when you clone this repository, as the generated clients are supposed to have their own repositories and be gitignored from the spec repo.


This directory contains per-major-API-version OpenAPI specifications of your API. For example, if your API has a v1 and v2, the spec directory would have v1 and v2 subdirectories. Each of these would contain at least header.yaml and shared.yaml "section files". Refer to section files reference for more information.


This directory contains your downstream template patches. These are applied to openapi-generator templates before the generation process using the apigentools templates command, thus allowing you to customize the upstream templates.


This directory contains processed upstream templates, i.e. IOW templates from openapi-generator with your template patches applied on top. These are usually gitignored from the spec repo; generate them locally using the apigentools templates command.

File Formats

This document serves as a reference of various file formats used by apigentools.


This is a configuration file for apigentools. It must be present in the spec repo for apigentools to work.


    "codegen_exec": "openapi-generator",
    "container_apigentools_image": "apigentools/apigentools:0.9.0",
    "languages": {
        "java": {
            "github_org_name": "my-github-org",
            "github_repo_name": "my-java-client",
            "spec_sections": {
                "v1": ["accounts.yaml"]
            "spec_versions": ["v1", "v2"],
            "version_path_template": "myapi_{{spec_version}}",
            "generate_extra_args": ["--skip-overwrite", "--generate-model-as-alias"]
    "spec_sections": {
        "v1": ["accounts.yaml", "users.yaml"],
        "v2": ["users.yaml"]
    "spec_versions": ["v1", "v2"],
    "generate_extra_args": ["--generate-model-as-alias"],
    "user_agent_client_name": "MyCompany"

The structure of the general config file is as follows, starting with top level keys:

Functions in Language Phase Commands

This section lists recognized functions for language phase commands, as mentioned in the section above.

Section Files

By design, apigentools doesn't operate on full OpenAPI specification files, but on "section files". These are, essentially, an exploded OpenAPI spec—these aid the development experience when working on these individual files instead of one huge file. The rules for these files are as follows:

On apigentools' invocation, these are merged into a single OpenAPI spec file and used as input for further operations, e.g. for openapi-generator.