Merge pull request #1113 from altro3/minor_fix_docs

Update libraries. Minor documentation fixes
micronaut-projects · Jul 17, 2023 · dfd5735 · dfd5735
2 parents 583fabc + 39e3493
commit dfd5735
Show file tree

Hide file tree

Showing 29 changed files with 101 additions and 76 deletions.
diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md
@@ -7,7 +7,7 @@ NOTE: If you are unsure about something and the issue is more of a question a be
 
 - [ ] Steps to reproduce provided
 - [ ] Stacktrace (if present) provided
-- [ ] Example that reproduces the problem uploaded to Github
+- [ ] Example that reproduces the problem uploaded to GitHub
 - [ ] Full description of the issue provided (see below)
 
 ### Steps to Reproduce
@@ -32,5 +32,5 @@ Tell us what happens instead
 
 ### Example Application
 
-- TODO: link to github repository with example that reproduces the issue
+- TODO: link to GitHub repository with example that reproduces the issue
 
diff --git a/MAINTAINING.md b/MAINTAINING.md
@@ -109,7 +109,7 @@ unnecessary upgrade burden on our users. Read the
 [Module Upgrade Strategy](https://github.com/micronaut-projects/micronaut-core/wiki/Module-Upgrade-Strategy) for more
 information.
 
-Note that if a new version arrives and we are not ready yet to do the upgrade, you need to
+Note that if a new version arrives, and we are not ready yet to do the upgrade, you need to
 [pin the old version](https://github.com/micronaut-projects/micronaut-build/#configuration-options), because otherwise,
 Renovate and our workflow will keep sending PRs. You should also create an issue to upgrade so that it's not forgotten.
 

diff --git a/README.md b/README.md
@@ -19,11 +19,11 @@ You can generate example applications at https://launch.micronaut.io by selectin
 
 ## Snapshots and Releases
 
-Snapshots are automatically published to [Sonatype Snapshots](https://s01.oss.sonatype.org/content/repositories/snapshots/io/micronaut/) using [Github Actions](https://github.com/micronaut-projects/micronaut-openapi/actions).
+Snapshots are automatically published to [Sonatype Snapshots](https://s01.oss.sonatype.org/content/repositories/snapshots/io/micronaut/) using [GitHub Actions](https://github.com/micronaut-projects/micronaut-openapi/actions).
 
 See the documentation in the [Micronaut Docs](https://docs.micronaut.io/latest/guide/index.html#usingsnapshots) for how to configure your build to use snapshots.
 
-Releases are published to Maven Central via [Github Actions](https://github.com/micronaut-projects/micronaut-openapi/actions).
+Releases are published to Maven Central via [GitHub Actions](https://github.com/micronaut-projects/micronaut-openapi/actions).
 
 A release is performed with the following steps:
 

diff --git a/gradle.properties b/gradle.properties
@@ -2,9 +2,9 @@ projectVersion=4.10.0-SNAPSHOT
 projectGroup=io.micronaut.openapi
 
 micronautDocsVersion=2.0.0
-micronautVersion=3.9.3
+micronautVersion=3.9.4
 micronautTestVersion=3.9.2
-groovyVersion=3.0.17
+groovyVersion=3.0.18
 spockVersion=2.3-groovy-3.0
 
 title=OpenAPI/Swagger Support

diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -1,16 +1,16 @@
 [versions]
-managed-swagger = "2.2.14"
+managed-swagger = "2.2.15"
 # Required to keep catalog compatibility with 3.4.x.  Can be removed for 4.0.0
-managed-swagger-compat = "2.2.14"
+managed-swagger-compat = "2.2.15"
 managed-javadoc-parser = "0.3.1"
 managed-jsoup = "1.16.1"
 managed-jakarta-validation-api = "3.0.2"
 
 # Versions beyond 0.62.2 require Java 11
 managed-html2md-converter = "0.62.2"
 
-kotlin = "1.8.22"
-kotlin-coroutines = "1.7.1"
+kotlin = "1.9.0"
+kotlin-coroutines = "1.7.2"
 jspecify = "0.3.0"
 jdt-annotation = "2.2.700"
 android-annotation = "1.6.0"

diff --git a/src/main/docs/guide/cli.adoc b/src/main/docs/guide/cli.adoc
@@ -1,5 +1,6 @@
 To create a project with OpenAPI/Swagger support using the Micronaut CLI, supply the `openapi` feature to the `features` flag. For example:
 
+[source,commandline]
 ----
 $ mn create-app my-openapi-app --features openapi
 ----

diff --git a/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc b/src/main/docs/guide/configuration/propertiesFileConfiguration.adoc
@@ -3,7 +3,7 @@ You can specify OpenAPI processing configuration in a file located at the root l
 It is possible to specify a different location and filename with the `micronaut.openapi.config.file` System property.
 
 .openapi.properties Example
-[source]
+[source,properties]
 ----
 micronaut.openapi.property.naming.strategy=KEBAB_CASE
 micronaut.openapi.target.file=myspecfile.yml
@@ -15,7 +15,7 @@ micronaut.openapi.target.file=myspecfile.yml
 Properties prefixed with `micronaut.openapi.expand` will be expanded at compile time, for instance with:
 
 .openapi.properties Property Resolution
-[source]
+[source,properties]
 ----
 micronaut.openapi.expand.api.version=v1.1
 micronaut.openapi.expand.openapi.description=A nice API

diff --git a/src/main/docs/guide/configuration/systemPropertyConfiguration.adoc b/src/main/docs/guide/configuration/systemPropertyConfiguration.adoc
@@ -1,4 +1,4 @@
-It is possible to tweak the OpenAPI processing via system properties. 
+It is possible to tweak the OpenAPI processing via system properties.
 
 For instance in gradle:
 
@@ -13,7 +13,8 @@ tasks.withType(JavaCompile) {
 }
 ----
 
-or in gradle.properties 
+or in gradle.properties
+[source,properties]
 ----
 org.gradle.jvmargs=-Dmicronaut.openapi.property.naming.strategy=SNAKE_CASE
 ----
@@ -38,4 +39,4 @@ or in maven:
         </plugin>
     </plugins>
 </build>
-----
+----
diff --git a/src/main/docs/guide/customSerializers.adoc b/src/main/docs/guide/customSerializers.adoc
@@ -1,6 +1,6 @@
 You can set custom classes to create different open api schemas for selected classes:
 
-[configuration]
+[source,yaml]
 ----
 micronaut:
   openapi:
@@ -11,7 +11,7 @@ micronaut:
 
 or by system properties:
 
-[source]
+[source,commandline]
 ----
 -Dmicronaut.openapi.schema.org.somepackage.MyComplexType=java.lang.String -Dmicronaut.openapi.schema.org.somepackage.MyComplexType2=java.lang.Integer
 ----
@@ -77,7 +77,7 @@ class MyJaxbElement3 {
 
 And set openapi properties to map classes to custom openapi schema classes:
 
-[configuartion]
+[source,yaml]
 ----
 micronaut:
   openapi:

diff --git a/src/main/docs/guide/endpoints/endpointservers.adoc b/src/main/docs/guide/endpoints/endpointservers.adoc
@@ -1,4 +1,5 @@
 You can also provide some servers for all endpoints with the `endpoints.server=<json array of io.swagger.v3.oas.models.servers.Server>` flag, for instance:
+[source,properties]
 ----
 endpoints.servers=[ \
     { \
@@ -22,4 +23,4 @@ endpoints.servers=[ \
       } \
     } \
   ]
-----
+----
diff --git a/src/main/docs/guide/endpoints/endpointspath.adoc b/src/main/docs/guide/endpoints/endpointspath.adoc
@@ -1,6 +1,7 @@
 If you are using a custom path for your endpoints use `endpoints.path` to set it:
 
 .openapi.properties *endpoints.path* property
+[source,properties]
 ----
 endpoints.path=/endpoints
 ...

diff --git a/src/main/docs/guide/endpoints/endpointssecurityrequirements.adoc b/src/main/docs/guide/endpoints/endpointssecurityrequirements.adoc
@@ -1,6 +1,7 @@
 You can also provide some security requirements for all endpoints with the `endpoints.security-requirements=<json array of io.swagger.v3.oas.models.security.SecurityRequirement>` flag, for instance:
 
 .openapi.properties endpoints.security-requirement property
+[source,properties]
 ----
 endpoints.security-requirements=[{"api_key": []}]
 ...

diff --git a/src/main/docs/guide/endpoints/endpointstags.adoc b/src/main/docs/guide/endpoints/endpointstags.adoc
@@ -1,6 +1,7 @@
 You can also provide some tags for all endpoints with the `endpoints.tags=<comma separated list of tags>` flag, for instance:
 
 .openapi.properties
+[source,properties]
 ----
 endpoints.tags=Management Endpoints
 ----
diff --git a/src/main/docs/guide/endpoints/micronautendpoints.adoc b/src/main/docs/guide/endpoints/micronautendpoints.adoc
@@ -6,6 +6,7 @@ dependency:micronaut-management[scope="implementation", version="{version}", gro
 
 and declare them in the <<propertiesFileConfiguration, openapi.properties>> file:
 
+[source,properties]
 ----
 endpoints.enabled=true
 endpoints.tags=Management Endpoints
@@ -19,6 +20,7 @@ endpoints.refresh.class=io.micronaut.management.endpoint.refresh.RefreshEndpoint
 The syntax is the following: `endpoints.<name>.class=<full class name of the endpoint>` where `name` is an arbitrary name.
 You can also add some tags, servers and security requirements to each endpoint:
 
+[source,properties]
 ----
 endpoints.refresh.class=io.micronaut.management.endpoint.refresh.RefreshEndpoint
 endpoints.refresh.servers=[{"url": "https://staging.gigantic-server.com/v1", "description": "Staging server"}]

diff --git a/src/main/docs/guide/exposingSwaggerOutput.adoc b/src/main/docs/guide/exposingSwaggerOutput.adoc
@@ -1,7 +1,7 @@
 If you wish to expose the generated OpenAPI yaml output from your running application you can simply add the necessary static resource to the application configuration. For example:
 
 .Exposing OpenAPI YAML
-[configuration]
+[source,yaml]
 ----
 micronaut:
     router:

diff --git a/src/main/docs/guide/gettingStarted.adoc b/src/main/docs/guide/gettingStarted.adoc
@@ -6,4 +6,15 @@ NOTE: For Kotlin the `openapi` dependency should be in the `kapt` scope and for
 
 To use the https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations[Swagger Annotations] add them to compile classpath
 
-dependency:swagger-annotations[scope="implementation", groupId="io.swagger.core.v3"]
+dependency:swagger-annotations[scope="compileOnly", groupId="io.swagger.core.v3"]
+
+NOTE: Also, do not forget that for the correct operation of the annotation processor, the correct parameter
+names in the controllers are required, therefore it is recommended that all libraries from which you plan
+to add controllers be compiled with the `-parameters` flag. For example like this (with gradle build):
+```groovy
+tasks.withType(JavaCompile).configureEach {
+    options.compilerArgs = [
+            '-parameters'
+    ]
+}
+```
diff --git a/src/main/docs/guide/openApiViews/mappingPath.adoc b/src/main/docs/guide/openApiViews/mappingPath.adoc
@@ -5,13 +5,13 @@ Thus, by default, the views expect to find the `yaml` under `/swagger`.
 If you change this mapping to something else:
 
 .Exposing Swagger YAML
-[configuration]
+[source,yaml]
 ----
 micronaut:
-    router:
-        static-resources:
-            swagger:
-                paths: classpath:META-INF/swagger
-                mapping: /swaggerYAML/**
+  router:
+    static-resources:
+      swagger:
+        paths: classpath:META-INF/swagger
+        mapping: /swaggerYAML/**
 ----
 You will need to set the `mapping.path` property accordingly: `micronaut.openapi.views.spec=mapping.path=swaggerYAML...`.
diff --git a/src/main/docs/guide/openApiViews/rapidoc.adoc b/src/main/docs/guide/openApiViews/rapidoc.adoc
@@ -52,17 +52,17 @@ See https://mrin9.github.io/RapiDoc/api.html[RapiDoc Options] for a description.
 To expose the `rapidoc` views, you also must expose the generated `yaml`:
 
 .Exposing Swagger YAML And Rapidoc Views
-[configuration]
+[source,yaml]
 ----
 micronaut:
-    router:
-        static-resources:
-            swagger:
-                paths: classpath:META-INF/swagger
-                mapping: /swagger/**
-            rapidoc:
-                paths: classpath:META-INF/swagger/views/rapidoc
-                mapping: /rapidoc/**
+  router:
+    static-resources:
+      swagger:
+        paths: classpath:META-INF/swagger
+        mapping: /swagger/**
+      rapidoc:
+        paths: classpath:META-INF/swagger/views/rapidoc
+        mapping: /rapidoc/**
 ----
 
 With the above configuration in place when you run your application you can access your Swagger documentation at +http://localhost:8080/rapidoc+.
diff --git a/src/main/docs/guide/openApiViews/redoc.adoc b/src/main/docs/guide/openApiViews/redoc.adoc
@@ -36,17 +36,17 @@ See https://github.com/Redocly/redoc#redoc-options-object[Redoc Options] for a d
 To expose the `redoc` views, you also must expose the generated `yaml`:
 
 .Exposing Swagger YAML And Redoc Views
-[configuration]
+[source,yaml]
 ----
 micronaut:
-    router:
-        static-resources:
-            swagger:
-                paths: classpath:META-INF/swagger
-                mapping: /swagger/**
-            redoc:
-                paths: classpath:META-INF/swagger/views/redoc
-                mapping: /redoc/**
+  router:
+    static-resources:
+      swagger:
+        paths: classpath:META-INF/swagger
+        mapping: /swagger/**
+      redoc:
+        paths: classpath:META-INF/swagger/views/redoc
+        mapping: /redoc/**
 ----
 
 With the above configuration in place when you run your application you can access your Swagger documentation at +http://localhost:8080/redoc+.
diff --git a/src/main/docs/guide/openApiViews/swaggerui.adoc b/src/main/docs/guide/openApiViews/swaggerui.adoc
@@ -30,26 +30,23 @@ The views will be generated to the `META-INF/swagger/views/swagger-ui` directory
 | `swagger-ui.tagsSorter` |
 |===
 
-
 See https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/configuration.md[Swagger UI Configuration] for a description.
 
 
-
-
 To expose the `swagger-ui` views, you also must expose the generated `yaml`:
 
 .Exposing Swagger YAML and Swagger UI Views
-[configuration]
+[source,yaml]
 ----
 micronaut:
-    router:
-        static-resources:
-            swagger:
-                paths: classpath:META-INF/swagger
-                mapping: /swagger/**
-            swagger-ui:
-                paths: classpath:META-INF/swagger/views/swagger-ui
-                mapping: /swagger-ui/**
+  router:
+    static-resources:
+      swagger:
+        paths: classpath:META-INF/swagger
+        mapping: /swagger/**
+      swagger-ui:
+        paths: classpath:META-INF/swagger/views/swagger-ui
+        mapping: /swagger-ui/**
 ----
 
 With the above configuration in place when you run your application you can access your Swagger documentation at +http://localhost:8080/swagger-ui+.
diff --git a/src/main/docs/guide/openApiViews/swaggerui/oauth2.adoc b/src/main/docs/guide/openApiViews/swaggerui/oauth2.adoc
@@ -21,13 +21,14 @@ When setting any of those properties, Micronaut will generate not only a `swagge
 
 An example configuration could be:
 
+[source,properties]
 ----
 micronaut.openapi.views.spec=swagger-ui.enabled=true,swagger-ui.theme=flattop,swagger-ui.oauth2RedirectUrl=http://localhost:8080/swagger-ui/oauth2-redirect.html,swagger-ui.oauth2.clientId=myClientId,swagger-ui.oauth2.scopes=openid,swagger-ui.oauth2.usePkceWithAuthorizationCodeGrant=true
 ----
 
 Then, you configure the `@SecurityScheme`:
 
-[source, java]
+[source,java]
 ----
 @SecurityScheme(name = "openid",
         type = SecuritySchemeType.OAUTH2,
@@ -82,7 +83,7 @@ public class OrderController {
 
 Do not forget to configure Micronaut Security accordingly:
 
-[configuration]
+[source,yaml]
 ----
 micronaut:
   security:

diff --git a/src/main/docs/guide/openApiViews/viewsGenerationWithPropertiesFile.adoc b/src/main/docs/guide/openApiViews/viewsGenerationWithPropertiesFile.adoc
@@ -1,7 +1,7 @@
 By default, the generation of views is disabled. You can enable views generation with a <<propertiesFileConfiguration, configuration properties file>>.
 
 .openapi.properties Example Views Generation Swagger-UI, Redoc, Rapidoc
-[source]
+[source,properties]
 ----
 micronaut.openapi.views.spec = swagger-ui.enabled=true,\
     redoc.enabled=true, \

diff --git a/src/main/docs/guide/openApiViews/viewsGenerationWithSystemProperties.adoc b/src/main/docs/guide/openApiViews/viewsGenerationWithSystemProperties.adoc
@@ -5,9 +5,9 @@ To turn it on you have to set the following system property `micronaut.openapi.v
 The string syntax is a series of comma-separated key-value pairs, to enable and configure the views.
 
 .System Property
-[source]
+[source,commandline]
 ----
-micronaut.openapi.views.spec=redoc.enabled=true,rapidoc.enabled=true,swagger-ui.enabled=true,swagger-ui.theme=flattop
+-Dmicronaut.openapi.views.spec=redoc.enabled=true,rapidoc.enabled=true,swagger-ui.enabled=true,swagger-ui.theme=flattop
 ----
 
 For instance in Gradle for Kotlin projects:

diff --git a/src/main/docs/guide/schemaDecorators.adoc b/src/main/docs/guide/schemaDecorators.adoc
@@ -1,6 +1,6 @@
 If you have some classes with same names in different packages you can set postfix like this:
 
-[configuration]
+[source,yaml]
 ----
 micronaut:
   openapi:
@@ -11,7 +11,7 @@ micronaut:
 
 or by system properties:
 
-[source]
+[source,commandline]
 ----
 -Dmicronaut.openapi.schema-postfix.org.api.v1_0_0=1_0_0 -Dmicronaut.openapi.schema-postfix.org.api.v2_0_0=2_0_0
 ----