Merge pull request #1156 from altro3/docs

Added `availableOptions` to documentation

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:
      * <p>
      * 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:
      * <p>
      * 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:
      * <p>
      * 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";

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);
+    }
+}
+----

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: `<project_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
+----
+|
+|===

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
+----

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