View Source OpenAPI.Reader (OpenAPI Generator v0.2.0)
Phase one of code generation
The read phase begins with one or more filenames (JSON or YAML) to read. Each document
should be the root of an OpenAPI description (usually beginning with an openapi
key and
version number). As the first step, they are parsed into large, nested maps and stored in the
state based on their filename. Then, each document is parsed into structs based on the OpenAPI
document definition.
Note that this library is not meant to "validate" OpenAPI descriptions. Errors may be thrown only when there are details missing that affect the operation of the code generator. Because of this, you may be able to "get away with" generating code from an incomplete or invalid document.
Note
Functions in this module are used by the main
OpenAPI
module. It is unlikely that you will call these functions directly, unless you are reimplementing one of the core functions. If this happens, please share your use-case with the maintainers; a plugin might be warranted.
Configuration
All configuration for this phase lives under the reader
key in each profile:
config :oapi_generator,
default: [
reader: [
...
]
]
The following options are available:
additional_files
: List of paths to supplemental root files of an API description. See Supplemental Descriptions below for more information. Defaults to no additional files.file
: Path to the (likely vendor-supplied) root file of an API description. This information is often supplied to themix api.gen
task, since individual client library maintainers may keep the API description document in different locations. However, if the API description is included in the client library repository, then this configuration can be used instead. If unset, the filename must be supplied tomix api.gen
.
Supplemental Descriptions
Sometimes, the OpenAPI description provided by a vendor is incomplete. Client library authors
may choose to write supplemental descriptions that "fill in the gaps". Although these files
must contain the root of an OpenAPI description (including an openapi
key and version number)
they may reference parts of the vendor-provided specification.
For example, GitHub provides special ID-based API routes like /repositories/{id}
that are
not documented in its OpenAPI description. A client library author may create a supplemental
description that looks like this (abbreviated):
openapi: 3.1.0
paths:
"/repositories/{id}":
get:
summary: Get a repository by ID
operationId: repos/get-by-id
parameters:
- "$ref": "#/components/parameters/id"
responses:
'200':
description: Response
content:
application/json:
schema:
"$ref": "#/components/schemas/full-repository"
Note that references to schemas contained in the vendor-supplied description must be modified
to use accurate paths. Assuming the supplemental file is committed in the client library
repository, authors may use the additional_files
configuration to ensure it is always
processed along with the vendor-supplied description:
config :oapi_generator,
default: [
reader: [
additional_files: ["path/to/supplement.yaml"]
]
]
During the reading phase, the two root documents will be combined as if each root key were
concatenated (for example, the paths from one file were copied to the other). Keys like info
will always use the vendor-supplied data. After the reading phase, the documents will be treated
as one API description, although plugins will have the opportunity to see the source of the data
when necessary.
Summary
Functions
@spec run(OpenAPI.State.t()) :: OpenAPI.State.t()
Run the reading phase of the code generator