Aster Web Data / Build an API

OpenAPI

Get an OpenAPI 3.1 description of your service, served by the server or exported in a build, for client generators and API tools.

A front-end team or a partner who builds a client needs an API description, and one written by hand drifts from the API it describes. Aster builds an OpenAPI 3.1 document from the same model as $metadata, so it changes when the model does, and client generators and documentation tools read a description that matches the running service. Each entity set, key, operation and navigation appears in it, and a property or set the model hides is left out.

Exporting

Write the document to a file with the export command. It loads the configuration, the database, the rules and the seed, writes the file, and exits, so it works in a build pipeline without a running server:

aster-webdata-server openapi --config config.yaml --output api.json

The output defaults to openapi.json. With several services in one configuration, --service NAME picks the one to export. --language fr selects a metadata language the configuration declares, and descriptions follow that language.

Set public_url for each service to the address clients reach it at. The exported document gives that URL as the server.

Serving

The server publishes the document at the service root, as openapi.json:

GET /odata/openapi.json

The path follows the OASIS OData-to-OpenAPI mapping, which recommends openapi.json under the service root. The document is openapi: "3.1.0". A client that asks for a language with Accept-Language gets the descriptions in that language, when the configuration has them. The document needs the same authentication as $metadata. The server builds it when it starts, rather than for each caller.

Set openapi: false for a service to turn the endpoint off. The export command still writes the file.

What the document covers

The document has these parts of the service:

• Entity sets, with their keys, and the operations on each: reads, inserts, updates and deletes that the set allows.
• Bound and unbound operations, with their parameters.
• JSON batch.
• One path for each published navigation, with keys on the targets of collection navigations.

Restrictions in the model remove the methods and query options a set does not allow. A property the model hides, and a set published as unreadable, are left out. Navigation cycles are not unfolded recursively.

The model's AsterData annotations appear as x-AsterData-* extensions.

Limits

A function that is not bound to a set carries only what its declaration states: the per-set read and query restrictions are not attached to its path.

An encoded field, such as an identifier stored as a number and sent as text, appears as a string with its encoding as the format, and the description says what is stored.

Next

• Model your data is where the document's sets and fields come from.
• Command line lists the openapi command's options.