Generating the documentation file

Summary

How to run composer openapi to produce your OpenAPI file from the attributes in src, how its output location, OpenAPI version and format are configured, and when the underlying zircote/swagger-php command is an option instead.

Details

Make sure that application.url in config/autoload/local.php is set to the URL of your instance of Dotkernel API. The generator publishes it as the first entry of the servers list.

Using your terminal, move to the root directory of your project.

Dotkernel API stores the OpenAPI attributes in the src directory, and the document root (info, servers, tags and security schemes) in config/autoload/openapi.global.php. Both are combined by bin/generate-openapi.php, which the openapi Composer script runs.

Generating the file

composer openapi

This scans src, adds the document root from configuration and writes the result to the file named by openapi.output_file, public/openapi.yaml by default. On success it prints the path of the file and the number of documented paths.

Output location, OpenAPI version and format

These are configured, not passed as flags. In config/autoload/openapi.global.php:

• output_file: where the file is written (default: public/openapi.yaml)
• openapi_version: the OpenAPI version, 3.1.0 by default (3.0.0 is also supported)
• the format follows the extension of output_file: .yaml for YAML or .json for JSON

For example, to write JSON:

'output_file' => 'public/openapi.json',

The output directory must already exist. See OpenAPI configuration for every key.

Using the zircote/swagger-php command directly

You can also run the underlying command:

./vendor/bin/openapi ./src --output public/openapi.yaml

This scans the attributes only. The generated file will not contain the info, servers, tags or security schemes that composer openapi adds from configuration, so use it only when you need the raw output. Its defaults differ: OpenAPI version 3.0.0 (override with --version 3.1.0) and the format taken from the output extension (force it with --format json or --format yaml).

FAQ

Q: What must I configure before generating?

A: application.url in config/autoload/local.php, which has to point at your own instance. Otherwise the generated file advertises the wrong server.

Q: Where do the output location, version and format come from?

A: From config/autoload/openapi.global.php: output_file, openapi_version, and the extension of output_file. See OpenAPI configuration.

Q: Which OpenAPI versions can I generate?

A: 3.1.0 (the configured default) and 3.0.0, selected with openapi_version.

Q: YAML or JSON?

A: The extension of output_file decides: .yaml gives YAML, .json gives JSON.

Q: Where should the generated file live?

A: Anywhere your renderer can read it; public/openapi.yaml is the default, since it can then be served directly. Point output_file outside public if the specification must not be served. See Render documentation.

Q: Do I have to regenerate after changing annotations?

A: Yes. The file is a static snapshot, so re-run composer openapi whenever the attributes or the configuration change.

Q: The command runs but my endpoint is missing. Why?

A: Its class is most likely outside src, its attributes are incomplete, or its tag is listed in exclude_tags. See Write documentation and Getting help.

Q: Why does the generated file differ from what ./vendor/bin/openapi ./src prints?

A: The raw command knows nothing about the configuration. composer openapi adds info, servers, tags and security schemes from config/autoload/openapi.global.php.