OpenAPI
=======

`OpenAPI <https://www.openapis.org/>`_ 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:

1. 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.
2. 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 <https://github.com/p1c2u/openapi-spec-validator>`_.

To run:

.. code:: bash

   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:

.. code:: bash

   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 <https://github.com/p1c2u/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:

.. code-block:: yaml

   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:

.. code-block:: yaml

   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 :doc:`JsonSchemaGenerator <json-schema>`:

* ``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
^^^^^^^^^^^^

.. click:: linkml.generators.openapigen:cli
    :prog: gen-openapi
    :nested: full

Code
^^^^

.. currentmodule:: linkml.generators.openapigen

.. autoclass:: OpenApiGenerator
    :members: serialize