Spec Repo

A "Spec Repo" is a repository (or, more generally, a directory), which 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 by commandline arguments passed to apigentools executable. More details about listed files follow.


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/major-API-version configuration configured 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" (in the sense that they're provided by you, not openapi-generator) templates. These need to go into a per-language directories, e.g. downstream-templates/java. Usually, you would put files here like a top-level README.md, top-level pom.xml and similar.


This directory contains code generated by apigentools, it's usually empty when you clone this repository, as the generated clients are supposed to have their own repositories and be git-ignored from the Spec Repo.


This directory contains per-major-API-version OpenAPI specifications of your API. For example, if your API has 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, IOW templates from openapi-generator with your template patches applied on top. These are usually git-ignored from the Spec Repo and you generate them locally using the apigentools templates command.

File Formats

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


This is a configuration file for apigentools and it must be present in the Spec Repo for apigentools to work.


    "codegen_exec": "openapi-generator",
    "languages": {
        "java": {
            "github_org_name": "my-github-org",
            "github_repo_name": "my-java-client",
            "spec_versions": ["v1"],
            "version_path_template": "myapi_{{spec_version}}"
    "server_base_urls": {
        "v1": "https://api.myserver.com/v1"
    "spec_sections": {
        "v1": ["accounts.yaml"]
    "spec_versions": ["v1"],
    "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 currently recognized functions for language phase commands as described in the section above:

Section Files

By design, apigentools doesn't operate on full OpenAPI specification files, but on so-called "section files". These are pretty much an exploded OpenAPI spec - this improves 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.