OpenAPI¶

OpenAPI is a specification for describing RESTful HTTP APIs. The OpenAPI generator produces an OpenAPI v3.0.3 specification in YAML from a LinkML schema.

Note

This generator produces a complete OpenAPI spec by combining a user-provided template (containing the API header, endpoints, and security schemes) with JSON Schema components derived from the LinkML schema.

Overview¶

The generator works in two stages:

The user provides an OpenAPI template — a valid OpenAPI v3.0.3 YAML file that defines the API metadata (title, version, servers), paths (endpoints), and security schemes.
The generator fills the components/schemas section with JSON Schema definitions generated from the LinkML schema, keeping only those classes that are transitively reachable from the endpoints.

Both the input template and the final output are automatically validated against the OpenAPI 3.0.3 specification using openapi-spec-validator.

To run:

gen-openapi personinfo.yaml --template api-template.yaml > personinfo.openapi.yaml

The --template / -t option is required when generating a concrete specification. If omitted, the generator prints a generic template that can be used as a starting point:

gen-openapi personinfo.yaml > api-template.yaml

OpenAPI Validation¶

The generator validates both the input template and the final output against the OpenAPI specification using openapi-spec-validator.

The openapi field in the template is checked against the expected version for the chosen output format (currently openapi303 → 3.0.3). If the versions do not match, the generator raises a ValueError.

Additionally, the template’s components/schemas section must declare each resource that is referenced by an endpoint, using two custom extension fields:

x-linkml-schema: The id of the LinkML schema being used. Must match exactly.
x-linkml-source: The name of the LinkML class that provides the schema for this resource.

Example template fragment:

components:
  schemas:
    Person:
      type: object
      x-linkml-schema: https://w3id.org/linkml/my_schema
      x-linkml-source: Person
    Organization:
      type: object
      x-linkml-schema: https://w3id.org/linkml/my_schema
      x-linkml-source: Organization

If the x-linkml-schema value does not match the schema being processed, the generator raises a ValueError. Any endpoint that references a resource not declared in components/schemas also raises an error.

Name Rewiring¶

If the name used for a resource in the OpenAPI template differs from the LinkML class name specified in x-linkml-source, the generator automatically rewires all $ref references and schema keys to use the template name.

For example, given this template:

components:
  schemas:
    PersonResource:
      type: object
      x-linkml-schema: https://w3id.org/linkml/my_schema
      x-linkml-source: Person

The generated spec will use PersonResource rather than Person throughout components/schemas and all $ref values.

JSON Schema Transformations¶

The generator applies several compatibility transforms to the JSON Schema generated by JsonSchemaGenerator:

const values become single-element enum arrays (OpenAPI 3.0 does not support const).
type lists (e.g. ["string", "null"] for nullable fields) are rewritten as anyOf.
$ref paths are rewritten from #/$defs/ to #/components/schemas/.
Class-level title fields (redundant with the schema key) are stripped.

Only classes transitively reachable from the endpoints are included in the output — unreferenced schemas are pruned automatically.

Docs¶

Command Line¶

gen-openapi¶

Generate an OpenAPI v3.0.3 spec with resources modelled with LinkML. If no OpenAPI template is provided, a generic one with placeholders for all the classes in the schema is printed out.

gen-openapi [OPTIONS] YAMLFILE

Options

-t, --template <template>¶: OpenAPI v3.0.3 template - includes the header, the endpoints and the security schemes

-V, --version¶: Show the version and exit.

-f, --format <format>¶

Output format

Default:: 'openapi303'
Options:: openapi303

--metadata, --no-metadata¶

Include metadata in output

Default:: True

--useuris, --metauris¶

Use class and slot URIs over model uris

Default:: True

-im, --importmap <importmap>¶: Import mapping file

--log_level <log_level>¶

Logging level

Default:: 'WARNING'
Options:: CRITICAL | ERROR | WARNING | INFO | DEBUG

-v, --verbose¶: Verbosity. Takes precedence over –log_level.

--mergeimports, --no-mergeimports¶: Merge imports into source file (default=mergeimports)

--stacktrace, --no-stacktrace¶

Print a stack trace when an error occurs

Default:: False

Arguments

YAMLFILE¶: Required argument

Code¶

class linkml.generators.openapigen.OpenApiGenerator(schema: str | ~typing.TextIO | ~linkml_runtime.linkml_model.meta.SchemaDefinition | ~linkml.utils.generator.Generator | ~pathlib.Path, schemaview: ~linkml_runtime.utils.schemaview.SchemaView | None = None, format: str | None = None, metadata: bool = True, useuris: bool | None = None, log_level: int | None = 30, mergeimports: bool | None = True, source_file_date: str | None = None, source_file_size: int | None = None, logger: ~logging.Logger | None = None, verbose: bool | None = None, output: str | None = None, namespaces: ~linkml_runtime.utils.namespaces.Namespaces | None = None, directory_output: bool = False, base_dir: str = None, metamodel_name_map: dict[str, str] = None, importmap: str | ~collections.abc.Mapping[str, str] | None = None, emit_prefixes: set[str] = <factory>, metamodel: ~linkml.utils.schemaloader.SchemaLoader = None, stacktrace: bool = False, include: str | ~pathlib.Path | ~linkml_runtime.linkml_model.meta.SchemaDefinition | None = None)[source]¶

Generates OpenAPI v3.0.3 specification YAML from a LinkML schema.

The generator composes a user-provided OpenAPI template (containing the API header, paths/endpoints, and security schemes) with JSON Schema components generated from the LinkML schema via JsonSchemaGenerator. Only classes referenced by the template’s endpoints (and their transitive dependencies) are included in the components/schemas section.

serialize(template_file: str = '', **kwargs) → str[source]¶: Generate an OpenAPI v3.0.3 spec from template_file and the loaded LinkML schema.