Merge pull request #179 from dotkernel/openapi-docs

updated openapi pages and references

Author: arhimede

docs/book/v7/introduction/file-structure.md

@@ -28,6 +28,7 @@ This folder contains:
 * `composer-post-install-script.php` - Runs after `composer install` and copies the shipped distributable config files into place; it asks nothing and needs no input
 * `doctrine` - Doctrine ORM console, used by the fixtures commands to populate the database tables
 * `generate-oauth2-keys.php` - Generates the OAuth2 key pair and encryption key into `data/oauth`
+* `generate-openapi.php` - Generates the OpenAPI document; run through `composer openapi`
 
 ## `config` folder
 
@@ -60,6 +61,7 @@ This folder contains all service-related local and global config files:
 * `local.test.php.dist` - Local configuration for functional tests
 * `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging. Not committed: the post-install script copies it out of `dotkernel/dot-mail` during installation
 * `mezzio.global.php` - Mezzio core config file
+* `openapi.global.php` - Configures the generated OpenAPI document: output file, version, info, servers, tags and security schemes
 * `problem-details.global.php` - Maps HTTP status codes to the `type` URI used in problem details responses
 * `response-header.global.php` - Defines headers per route
 * `templates.global.php` - Configures `Api\App\Template\RendererInterface`, including the `phtml` template extension

docs/book/v7/introduction/introduction.md

@@ -148,7 +148,7 @@ A: REST APIs in a microservices setup, headless CMS backends, e-commerce and Saa
 
 **Q: Where do I configure each feature?**
 
-A: OAuth2 in `config/autoload/local.php`, RBAC in `config/autoload/authorization.global.php`, content negotiation in `config/autoload/content-negotiation.global.php`; the OpenAPI documentation is generated rather than configured.
+A: OAuth2 in `config/autoload/local.php`, RBAC in `config/autoload/authorization.global.php`, content negotiation in `config/autoload/content-negotiation.global.php`; the OpenAPI documentation is generated by `composer openapi` and configured in `config/autoload/openapi.global.php`.
 
 **Q: How do I register a new module?**
 

docs/book/v7/openapi/configuration.md

@@ -0,0 +1,145 @@
+# OpenAPI configuration
+
+## Summary
+
+The values that make up the root of the generated OpenAPI document — where the file is written, the OpenAPI version, `info`, `servers`, external documentation, tags and security schemes — are not attributes.
+They live in `config/autoload/openapi.global.php` and `application.url`, and `bin/generate-openapi.php` reads them when you run `composer openapi`.
+
+## Details
+
+PHP attribute arguments must be constant expressions, so an `OA\Server` attribute cannot read the base URL out of your local config.
+For that reason the document root is assembled by `bin/generate-openapi.php` from configuration after the scan of `src`, while paths and schemas stay in each module's `OpenAPI.php`.
+
+The environment-independent keys belong in `config/autoload/openapi.global.php`, under the `openapi` key.
+The values that differ per environment belong in your local config:
+
+- `application.url` in `config/autoload/local.php`: the URL of your instance of **Dotkernel API**, published as the first entry of `servers` (use no trailing slash)
+- `openapi.server_description` (optional): the label of that first server (example: `Dev`, `Staging` or `Production`)
+
+## Configuration keys
+
+### `output_file`
+
+Where `composer openapi` writes the document.
+Default: `public/openapi.yaml`.
+The format follows the file extension: `.yaml` or `.json`.
+
+`public/` is what makes the document reachable over HTTP.
+If the specification should not be served, point this key outside it, for example `data/openapi.yaml`.
+The output directory must already exist.
+
+### `openapi_version`
+
+The OpenAPI version of the generated document.
+Default: `3.1.0`.
+
+### `info`
+
+Becomes the `OA\Info` object:
+
+- `title`: title shown in the UI (default: `Dotkernel API`)
+- `version`: API version (default: `1.0`)
+
+### `external_docs`
+
+Becomes the `OA\ExternalDocumentation` object, and is omitted when `url` is not set:
+
+- `description`: describes the purpose of the document
+- `url`: external documentation URL
+
+### `servers`
+
+Servers published after the project's own URL.
+The first server is always `application.url`, labelled with `openapi.server_description`.
+Each entry has a `url` and an optional `description`:
+
+```php
+'servers' => [
+    ['url' => 'https://sandbox.example.com', 'description' => 'Sandbox'],
+],
+```
+
+A URL that is already in the list is written once, and the first occurrence keeps its description.
+An entry without a non-empty `url` makes `composer openapi` fail.
+
+### `tags`
+
+A map of tag name to description, published as the document's `tags` block.
+Every tag you use in a module's `OpenAPI.php` should be declared here, so the renderer can describe the group.
+
+```php
+'tags' => [
+    'Book' => 'Book records.',
+],
+```
+
+### `exclude_tags`
+
+A list of tags whose endpoints are left out of the generated document.
+Both the paths and the schemas only they referenced disappear, and the names are also dropped from the `tags` block.
+
+```php
+'exclude_tags' => [
+    'Book',
+],
+```
+
+The endpoints keep working: this hides them from the document, it is not access control.
+Match the tag exactly as the operations declare it, including spaces.
+
+### `generated_timezone`
+
+An IANA timezone identifier (default: `UTC`) used for `info.x-generated`, the ISO-8601 timestamp of when the document was built.
+Set it to `null` to leave the field out, which also makes the output identical between runs, useful if you commit the document.
+
+### `security_schemes`
+
+A map of scheme name to definition, published as `OA\SecurityScheme` objects.
+The shipped schemes are:
+
+```php
+'security_schemes' => [
+    'AuthToken'           => [
+        'type'          => 'http',
+        'bearer_format' => 'JWT',
+        'scheme'        => 'bearer',
+    ],
+    'ErrorReportingToken' => [
+        'type' => 'apiKey',
+        'name' => 'Error-Reporting-Token',
+        'in'   => 'header',
+    ],
+],
+```
+
+Each definition accepts `type`, `name`, `in`, `bearer_format` and `scheme`.
+
+## FAQ
+
+**Q: Where do I set the server URL?**
+
+A: In `application.url`, in `config/autoload/local.php`.
+The generator publishes it as the first server.
+See [Generate documentation](generate-documentation.md).
+
+**Q: Why are these values not attributes?**
+
+A: Attribute arguments must be constant expressions, so they cannot read the base URL from local config.
+The generator builds the document root from configuration instead.
+
+**Q: How do I publish more than one server?**
+
+A: Add entries to `openapi.servers`, each with a `url` and an optional `description`.
+
+**Q: How do I stop publishing a module's endpoints?**
+
+A: List its tag in `exclude_tags` and run `composer openapi` again.
+The endpoints keep working; they are only hidden from the document.
+
+**Q: How do I make the output reproducible between runs?**
+
+A: Set `generated_timezone` to `null`, so no build timestamp is written.
+
+**Q: Where do the components these keys produce show up?**
+
+A: See [Initialized components](initialized-components.md) for how each one is described.

docs/book/v7/openapi/generate-documentation.md

@@ -2,94 +2,94 @@
 
 ## Summary
 
-How to run `zircote/swagger-php` against the `src` directory to produce your OpenAPI file: printing it to the terminal, writing it to a chosen location, and selecting the OpenAPI version (`3.0.0` or `3.1.0`) and output format (`yaml` or `json`).
+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 in `src/App/src/OpenAPI.php`, on the line with `#[OA\Server` the value of `url` is set to the of URL of your instance of **Dotkernel API**.
+> 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, so that's the path we will use for generating the static documentation file.
+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.
 
-## Methods of generating a documentation file
-
-### Without saving it to a file
+## Generating the file
 
 ```shell
-./vendor/bin/openapi ./src
+composer openapi
 ```
 
-This will output the generated content to the terminal.
+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.
 
-### Place it in a custom location
+### Output location, OpenAPI version and format
 
-```shell
-./vendor/bin/openapi ./src --output public/openapi.yaml
-```
+These are configured, not passed as flags.
+In `config/autoload/openapi.global.php`:
 
-This will place the generated file `openapi.yaml` in the `public` directory.
+- `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
 
-### Specify OpenAPI version
+For example, to write JSON:
 
-Supported OpenAPI versions are `3.0.0` and `3.1.0`, `3.0.0` being the default version.
-
-The below command will specify both the output location and the OpenAPI version:
-
-```shell
-./vendor/bin/openapi ./src --version 3.1.0
+```php
+'output_file' => 'public/openapi.json',
 ```
 
-### Specify an output file format
+The output directory must already exist.
+See [OpenAPI configuration](configuration.md) for every key.
 
-Supported file formats are `yaml` and `json`, `yaml` being the default format.
+### Using the `zircote/swagger-php` command directly
 
-The below command will specify the output location and `zircote/swagger-php` will determine the file format:
+You can also run the underlying command:
 
 ```shell
-./vendor/bin/openapi ./src --output public/openapi.json
-```
-
-Or be specific about the format by appending the `--format` argument:
-
-```shell
-./vendor/bin/openapi ./src --output public/openapi.json --format json
+./vendor/bin/openapi ./src --output public/openapi.yaml
 ```
 
-These will place the generated file `openapi.json` in the `public` directory.
+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: The `url` value on the `#[OA\Server` line in `src/App/src/OpenAPI.php`, which has to point at your own instance.
+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: Why is `./src` the path passed to the command?**
+**Q: Where do the output location, version and format come from?**
 
-A: Because Dotkernel API keeps its OpenAPI attributes in the `src` directory.
-The generator scans that path for annotated classes.
+A: From `config/autoload/openapi.global.php`: `output_file`, `openapi_version`, and the extension of `output_file`.
+See [OpenAPI configuration](configuration.md).
 
 **Q: Which OpenAPI versions can I generate?**
 
-A: `3.0.0` (the default) and `3.1.0`, selected with `--version`.
+A: `3.1.0` (the configured default) and `3.0.0`, selected with `openapi_version`.
 
 **Q: YAML or JSON?**
 
-A: YAML is the default.
-Use a `.json` output filename and the generator picks JSON, or state it explicitly with `--format 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 common choice, since it can then be served directly.
+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](render-documentation.md).
 
 **Q: Do I have to regenerate after changing annotations?**
 
 A: Yes.
-The file is a static snapshot, so re-run the command whenever the annotations change.
+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 the scanned path, or its attributes are incomplete.
+A: Its class is most likely outside `src`, its attributes are incomplete, or its tag is listed in `exclude_tags`.
 See [Write documentation](write-documentation.md) and [Getting help](getting-help.md).
+
+**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`.

docs/book/v7/openapi/getting-help.md

@@ -8,7 +8,7 @@ Where to look when an OpenAPI annotation does not behave as expected: the specif
 
 - consult the OpenAPI [specs](https://spec.openapis.org/oas/latest.html) for a complete reference of the presented objects
 - see more examples of OpenAPI object representations in `zircote/swagger-php`'s [GitHub repository](https://zircote.github.io/swagger-php/guide/examples.html)
-- consult `zircote/swagger-php`'s [online documentation](http://zircote.github.io/swagger-php/guide/generating-openapi-documents.html) or run the following command to see their help page:
+- consult `zircote/swagger-php`'s [online documentation](http://zircote.github.io/swagger-php/guide/generating-openapi-documents.html) or run the following command to see the help page of the underlying `zircote/swagger-php` command (the project's own generator is `composer openapi`):
 
 ```shell
 ./vendor/bin/openapi --help