From 053c36a5298688a038fa003a53cc1d7ec12c854e Mon Sep 17 00:00:00 2001 From: altro3 Date: Sat, 5 Aug 2023 20:35:16 +0700 Subject: [PATCH] Added `availableOptions` to documentation --- .../visitor/OpenApiConfigProperty.java | 34 +++---- .../applicationConfiguration.adoc | 43 +++++++++ .../guide/configuration/availableOptions.adoc | 93 +++++++++++++++++++ .../propertiesFileConfiguration.adoc | 9 ++ src/main/docs/guide/toc.yml | 2 + 5 files changed, 162 insertions(+), 19 deletions(-) create mode 100644 src/main/docs/guide/configuration/applicationConfiguration.adoc create mode 100644 src/main/docs/guide/configuration/availableOptions.adoc diff --git a/openapi/src/main/java/io/micronaut/openapi/visitor/OpenApiConfigProperty.java b/openapi/src/main/java/io/micronaut/openapi/visitor/OpenApiConfigProperty.java index 0e73c62927..970bb48999 100644 --- a/openapi/src/main/java/io/micronaut/openapi/visitor/OpenApiConfigProperty.java +++ b/openapi/src/main/java/io/micronaut/openapi/visitor/OpenApiConfigProperty.java @@ -139,10 +139,6 @@ public interface OpenApiConfigProperty { * Loaded micronaut-http server context path property. */ String MICRONAUT_SERVER_CONTEXT_PATH = "micronaut.server.context-path"; - /** - * Final calculated openapi filenames. - */ - String MICRONAUT_INTERNAL_OPENAPI_FILENAMES = "micronaut.internal.openapi.filenames"; /** * Loaded micronaut-http-server-netty property (json-view.enabled). */ @@ -157,10 +153,10 @@ public interface OpenApiConfigProperty { * Also, you can set it in your application.yml file like this: *

* micronaut: - * openapi: - * schema: - * org.somepackage.MyComplexType: java.lang.String - * org.somepackage.MyComplexType2: java.lang.Integer + * openapi: + * schema: + * org.somepackage.MyComplexType: java.lang.String + * org.somepackage.MyComplexType2: java.lang.Integer * ... */ String MICRONAUT_OPENAPI_SCHEMA = "micronaut.openapi.schema"; @@ -174,10 +170,10 @@ public interface OpenApiConfigProperty { * Also, you can set it in your application.yml file like this: *

* micronaut: - * openapi: - * schema-postfix: - * org.api.v1_0_0: 1_0_0 - * org.api.v2_0_0: 2_0_0 + * openapi: + * schema-postfix: + * org.api.v1_0_0: 1_0_0 + * org.api.v2_0_0: 2_0_0 * ... */ String MICRONAUT_OPENAPI_SCHEMA_PREFIX = "micronaut.openapi.schema-prefix"; @@ -191,13 +187,13 @@ public interface OpenApiConfigProperty { * Also, you can set it in your application.yml file like this: *

* micronaut: - * openapi: - * group: - * my-group1: - * title: Title 1 - * filename: swagger-${group}-${apiVersion}-${version}.yml - * my-group2: - * title: Title 2 + * openapi: + * group: + * my-group1: + * title: Title 1 + * filename: swagger-${group}-${apiVersion}-${version}.yml + * my-group2: + * title: Title 2 * ... */ String MICRONAUT_OPENAPI_GROUPS = "micronaut.openapi.groups"; diff --git a/src/main/docs/guide/configuration/applicationConfiguration.adoc b/src/main/docs/guide/configuration/applicationConfiguration.adoc new file mode 100644 index 0000000000..393353f5c2 --- /dev/null +++ b/src/main/docs/guide/configuration/applicationConfiguration.adoc @@ -0,0 +1,43 @@ +It is possible to tweak the OpenAPI processing via standard way with micronaut environments (application.yml file). + +.application.yml Example +[source,yaml] +---- +micronaut: + openapi: + target: + file: myspecfile.yml + property: + naming: + strategy: KEBAB_CASE +---- + +Also, you can use properties from `application.yml` file for placeholders. + +.application.yml Sample properties for placeholders +[source,yaml] +---- +my: + api: + version: 1.0.0 + title: My title + api-description: My description +---- + +.Application.java Simple Application +[source,java] +---- +@OpenAPIDefinition( + info = @Info( + title = "${my.api.version}", + version = "${my.api.title}", + description = "${my.api.api-description}" + ) +) +public class Application { + + public static void main(String[] args) { + Micronaut.run(Application.class); + } +} +---- diff --git a/src/main/docs/guide/configuration/availableOptions.adoc b/src/main/docs/guide/configuration/availableOptions.adoc new file mode 100644 index 0000000000..36d4a3229b --- /dev/null +++ b/src/main/docs/guide/configuration/availableOptions.adoc @@ -0,0 +1,93 @@ +|=== +|`micronaut.openapi.enabled` | System property that enables or disables open api annotation processing. | Default: `true` +|`micronaut.openapi.config.file` | System property that enables setting the open api config file. | +|`micronaut.openapi.server.context.path` | System property for server context path. | +|`micronaut.openapi.property.naming.strategy` | System property for naming strategy. One jackson PropertyNamingStrategy. | Default: `LOWER_CAMEL_CASE` +|`micronaut.openapi.views.spec` | System property for views specification. | +|`micronaut.openapi.target.file` | System property that enables setting the target file to write to. | Default: `META-INF/swagger/${applicationName}-${version}.yml` +|`micronaut.openapi.views.dest.dir` | System property that specifies the path where the generated UI elements will be located. | Default: `META-INF/swagger/views/` +|`micronaut.openapi.additional.files` | System property that specifies the location of additional swagger YAML and JSON files to read from. | +|`micronaut.openapi.project.dir` | System property that specifies the location of current project. Need to set this property mannually if you use kotlin (to save incremental annotation processing) or have some troubles with auto calculation project path. | Default: calculated automatically +|`micronaut.openapi.security.default-schema-name` | System property that specifies the default security schema name, if it's not specified by annotation SecurityScheme. | +|`micronaut.openapi.security.enabled` | Is this property true, micronaut-openapi will process micronaut-security properties and annotations to construct openapi security schema. | Default: `true` +|`micronaut.openapi.field.visibility.level` | System property that specifies the schema classes fields visibility level. By default, only public fields visibile. + +{nbsp} + +**Available values:** + +PRIVATE + +PACKAGE + +PROTECTED + +PUBLIC | Default: `PUBLIC` +|`micronaut.openapi.json.format` | Is this property true, output file format will be JSON, otherwise YAML. | Default: `false` +|`micronaut.openapi.filename` | The name of the result swagger file. | Default: `${info.title}-${info.version}.yml`, if info block not set, filename will be `swagger.yml`. +|`micronaut.openapi.environments` | Active micronaut environments which will be used for @Requires annotations. | +|`micronaut.openapi.environments.enabled` | Is this property true, properties wll be loaded in the standard way from application.yml. Also, environments from `micronaut.openapi.environments` property will set as additional environments, if you want to set specific environment name for openAPI generator. | Default: `true` +|`micronaut.openapi.versioning.enabled` | Is this property true, micronaut-openapi will process micronaut-router versioning prpoerties and annotations. | Default: `true` +|`micronaut.server.context-path` | `micronaut-http` server context path property. | +|`micronaut.internal.openapi.filenames` | Final calculated openapi filenames. | +|`jackson.json-view.enabled` | `micronaut-http` property (`json-view.enabled`). | Default: `false` +|`micronaut.openapi.json.view.default.inclusion` | Property that determines whether properties that have no view annotations are included in JSON serialization views. If enabled, non-annotated properties will be included; when disabled, they will be excluded. | Default: `true` +|`micronaut.openapi.expand.*` | Prefix for expandable properties. These properties can be used only for placeholders. | +|`micronaut.openapi.config.file.locations` | Config file locations. By default, micronaut-openapi search config in standard path: `/src/main/resources/` + +{nbsp} + +You can set your custom paths separated by `,`. To set absolute paths use prefix `file:`, +classpath paths use prefix `classpath:` or use prefix `project:` to set paths from project +directory. | +|`micronaut.openapi.schema.*` | Properties prefix to set custom schema implementations for selected clases. + +For example, if you want to set simple `java.lang.String` class to some complex `org.somepackage.MyComplexType` class you need to write: + +[source,properties] +---- +micronaut.openapi.schema.org.somepackage.MyComplexType=java.lang.String + +---- +Also, you can set it in your `application.yml` file like this: + +[source,yaml] +---- +micronaut: + openapi: + schema: + org.somepackage.MyComplexType: java.lang.String + org.somepackage.MyComplexType2: java.lang.Integer +---- +| +|`micronaut.openapi.schema-prefix` + +`micronaut.openapi.schema-postfix` | Properties prefix to set schema name prefix or postfix by package. + +For example, if you have some classes with same names in different packages you can set postfix like this: + +[source,properties] +---- +micronaut.openapi.schema-postfix.org.api.v1_0_0=1_0_0 +micronaut.openapi.schema-postfix.org.api.v2_0_0=2_0_0 +---- +Also, you can set it in your `application.yml` file like this: +[source,yaml] +---- +micronaut: + openapi: + schema-postfix: + org.api.v1_0_0: 1_0_0 + org.api.v2_0_0: 2_0_0 + schema-prefix: + org.api.v1_0_0: public + org.api.v2_0_0: private +---- +| +|`micronaut.openapi.groups.*` | Properties prefix to set custom schema implementations for selected clases. + +For example, if you want to set simple 'java.lang.String' class to some complex 'org.somepackage.MyComplexType' class you need to write: + +[source] +---- +-Dmicronaut.openapi.group.my-group1.title="Title 1" +---- + +Also, you can set it in your application.yml file like this: + +[source,yaml] +---- +micronaut: + openapi: + group: + my-group1: + title: Title 1 + filename: swagger-${group}-${apiVersion}-${version}.yml + my-group2: + title: Title 2 +---- +| +|=== diff --git a/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc b/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc index 391c5d6449..08daff57d5 100644 --- a/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc +++ b/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc @@ -61,3 +61,12 @@ info: url: https://foo.bar version: "v1.1" ---- + +NOTE: So, `micronaut-openapi` expanded properties is old solution, now you can also use any properties for placeholders. For example, if you set properties without prefix `micronaut.openapi.expand` micronaut-openapi will process them as with this prefix. + +.openapi.properties Property Resolution without prefix +[source,properties] +---- +api.version=v1.1 +openapi.description=A nice API +---- diff --git a/src/main/docs/guide/toc.yml b/src/main/docs/guide/toc.yml index 18dcd8f8fa..d081baa3f4 100644 --- a/src/main/docs/guide/toc.yml +++ b/src/main/docs/guide/toc.yml @@ -7,6 +7,8 @@ configuration: title: OpenAPI Processing Options propertiesFileConfiguration: Configuring OpenAPI Processing with a properties file systemPropertyConfiguration: Configuring OpenAPI Processing with system properties + applicationConfiguration: Configuring OpenAPI Processing with an application.yml file + availableOptions: Available OpenAPI processing options exposingSwaggerOutput: Exposing Swagger Output controllers: OpenAPI Generation for Controllers namingstrategy: Naming Strategy