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
.gitignore
This is a standard .gitignore file.
config/
This is a directory containing config.json, which is a configuration file for apigentools.
config/languages/
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>
.
downstream-templates/
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.md
s, top-level pom.xml
s, etc., here.
generated/
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.
spec/
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.
template-patches/
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.
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.
config/config.json
This is a configuration file for apigentools. It must be present in the spec repo for apigentools to work.
Example:
{
"codegen_exec": "openapi-generator",
"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"]
}
},
"server_base_urls": {
"v1": "https://api.myserver.com/v1"
},
"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:
codegen_exec
- Name of the executable of the code generating tool.languages
- Settings for individual languages; contains a mapping of language names to their settings.- individual language settings:
commands
- Commands to execute before/after code generation; commands are executed in two phases -pre
(executed before code generation) orpost
(executed after code generation). Note that each command is run once for each of the langauge'sspec_versions
, and inside the directory with code for that spec version.- phase commands - Each phase can contain a list of commands to be executed; each command is represented as a map:
description
- A description of the command.commandline
- The command itself; the items in the list are strings and, potentially, functions that represent callbacks to the Python code. Each function is represented as a map:function
- Name of the function (see below for list of recognized functions).args
- List of args to pass to the function in Python code (as in*args
).kwargs
- Mapping of args to pass to the function in Python code (as in**kwargs
).- The result of the function call is then used in the actual command line call.
command_env
- Additional environment values with which both commands fromcommands
and code generation itself are executed (mapping of environment variable names to their values)github_org_name
- Name of the Github organization of the client for this language.github_repo_name
- Name of the Github repository of the client for this language.spec_sections
- Same as top-levelspec_sections
. Use to override the subset of spec sections to generate for each spec version of this language. For every spec version not specified as a key, the top-level list of sections for this spec version is used.spec_versions
- Same as top-levelspec_versions
. Use to override the subset of major versions to generate for this language. If not specified, the top-levelspec_versions
value is used.upstream_templates_dir
- Name of the directory in openapi-generator that holds templates for this language. This is optional and, by default, the name of the language is used.version_path_template
- Mustache template for the name of the subdirectory in the Github repo where code for individual major versions of the API will end up, e.g. withmyapi_{{spec_version}}
as value and agithub_repo_name
of valuemy-java-client
, the code forv1
of the API will end up inmyapi-java-client/myapi_v1
generate_extra_args
- Same as top-levelgenerate_extra_args
. Use to override the additional arguments to pass to theopenapi-generator
call for this language.
server_base_urls
- Mapping of major spec versions (these must be inspec_versions
) to URLs of servers that provide them.spec_sections
- Mapping of major spec versions (these must be inspec_versions
) to lists of files with paths/tags/components definitions to merge when creating full spec. Files not explicitly listed here are ignored.spec_versions
- List of major versions currently known and operated on. These must be subdirectories of thespec
directory.user_agent_client_name
- The HTTP User Agent string will be set to{user_agent_client_name}/{package_version}/{language}
.generate_extra_args
- Additional arguments to pass to theopenapi-generator
call.
Functions in Language Phase Commands
This section lists recognized functions for language phase commands, as mentioned in the section above.
glob
- runs Python'sglob.glob
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:
- The below rules apply specification of every major API version.
spec/<MAJOR_API_VERSION>/header.yaml
is expected to be present. This is a header file that should only contain OpenAPI keysopenapi
,info
, andexternalDocs
(note thatservers
is filled in dynamically by apigentools based on yourconfig/config.yaml
).spec/<MAJOR_API_VERSION>/shared.yaml
is expected to be present. This is a file containing any OpenAPI objects that are referenced from more than one "section"—components
(which includesschemas
andsecurity_schemes
),security
,andtags
.- Any other
.yaml
files with arbitrarycomponents
,paths
,security
, andtags
may be added. Note that these have to be explicitly listed inconfig/config.json
in order to be used.
On apigentools' invocation, these are merged into a single OpenAPI spec file and used as input for further operations, e.g. for openapi-generator.