New Feature: OpenAPI groups and support micronaut @Version (#1067)

Introducing a new feature: openapi groups (the same feature as in springdoc-openapi). Now you can group endpoints to get multiple swagger files - one file for each group. This is useful when you have multiple API versions or want to separate your API based on some other criteria.


---------

Co-authored-by: micronaut-build <micronaut-build-account@grails.org>

gradle.properties

@@ -1,4 +1,4 @@
-projectVersion=4.9.2-SNAPSHOT
+projectVersion=4.10.0-SNAPSHOT
 projectGroup=io.micronaut.openapi
 
 micronautDocsVersion=2.0.0

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIDecorator.java

@@ -22,7 +22,7 @@
 
 import io.micronaut.context.annotation.AliasFor;
 
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
 
 /**
  * The annotation can be used to add suffix and prefix for operationIds. For example, when you have
@@ -41,7 +41,7 @@
  *
  * @since 4.5.0
  */
-@Retention(RUNTIME)
+@Retention(SOURCE)
 @Documented
 @Target({ElementType.TYPE, ElementType.METHOD})
 public @interface OpenAPIDecorator {
@@ -50,18 +50,21 @@
      * @return Prefix for operation ids.
      */
     String value() default "";
+
     /**
      * @return Prefix for operation ids.
      */
     @AliasFor(member = "value")
     String opIdPrefix() default "";
+
     /**
      * @return Suffix for operation ids.
      */
     String opIdSuffix() default "";
+
     /**
      * @return is this flag false, prefixes and suffixes will not be added to operationId
-     * if operationId is set explicitly in the {@link io.swagger.v3.oas.annotations.Operation} annotation
+     *     if operationId is set explicitly in the {@link io.swagger.v3.oas.annotations.Operation} annotation
      */
     boolean addAlways() default true;
 }

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIGroup.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2017-2023 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.openapi.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import io.micronaut.context.annotation.AliasFor;
+
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+/**
+ * With this annotation, you can specify one or more groups that this endpoint will be included in,
+ * as well as specify groups from which this endpoint should be excluded.
+ *
+ * @since 4.10.0
+ */
+@Retention(SOURCE)
+@Documented
+@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.METHOD})
+public @interface OpenAPIGroup {
+
+    /**
+     * @return The names of the OpenAPi groups.
+     */
+    @AliasFor(member = "names")
+    String[] value() default {};
+
+    /**
+     * @return The names of the OpenAPi groups.
+     */
+    @AliasFor(member = "value")
+    String[] names() default {};
+
+    /**
+     * @return The names of the OpenAPi groups to exclude endpoints from.
+     */
+    String[] exclude() default {};
+}

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIGroupInfo.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2017-2023 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.openapi.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import io.micronaut.context.annotation.AliasFor;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+/**
+ * With this annotation, you can specify the OpenAPIDefinition description that will be inserted
+ * into a specific swagger file, only for this group. Thus, you can make different descriptions
+ * for different groups.
+ *
+ * @since 4.10.0
+ */
+@Repeatable(OpenAPIGroupInfos.class)
+@Retention(SOURCE)
+@Documented
+@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
+public @interface OpenAPIGroupInfo {
+
+    /**
+     * @return The names of the OpenAPi groups.
+     */
+    @AliasFor(member = "names")
+    String[] value() default {};
+
+    /**
+     * @return The names of the OpenAPi groups.
+     */
+    @AliasFor(member = "value")
+    String[] names() default {};
+
+    /**
+     * @return OpenAPI object describing information about group.
+     */
+    OpenAPIDefinition info();
+}

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIGroupInfos.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2017-2023 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.openapi.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
+/**
+ * Allows {@link OpenAPIGroupInfo} to be repeatable.
+ *
+ * @since 4.10.0
+ */
+@Documented
+@Retention(SOURCE)
+@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
+public @interface OpenAPIGroupInfos {
+
+    /**
+     * @return An array of {@link OpenAPIGroupInfo}
+     */
+    OpenAPIGroupInfo[] value() default {};
+}

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIInclude.java

@@ -15,17 +15,17 @@
  */
 package io.micronaut.openapi.annotation;
 
-import io.micronaut.context.annotation.AliasFor;
-import io.swagger.v3.oas.annotations.security.SecurityRequirement;
-import io.swagger.v3.oas.annotations.tags.Tag;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import io.micronaut.context.annotation.AliasFor;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import static java.lang.annotation.RetentionPolicy.SOURCE;
 
 /**
  * The annotation can be used to include additional io.micronaut.http.annotation.Controller or
@@ -35,7 +35,7 @@
  * @author Denis Stepanov
  */
 @Repeatable(OpenAPIIncludes.class)
-@Retention(RUNTIME)
+@Retention(SOURCE)
 @Documented
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 public @interface OpenAPIInclude {
@@ -57,6 +57,20 @@
     @AliasFor(member = "value")
     String[] classNames() default {};
 
+    /**
+     * @return Array of groups to which this controller should be included.
+     *
+     * @since 4.10.0
+     */
+    String[] groups() default {};
+
+    /**
+     * @return Array of groups to which this controller should not be included.
+     *
+     * @since 4.10.0
+     */
+    String[] groupsExcluded() default {};
+
     /**
      * @return Custom URI for controller
      *

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIIncludes.java

@@ -20,15 +20,15 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
 
 /**
  * Allows {@link OpenAPIInclude} to be repeatable.
  *
  * @author Denis Stepanov
  */
 @Documented
-@Retention(RUNTIME)
+@Retention(SOURCE)
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 public @interface OpenAPIIncludes {
 

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPIManagement.java

@@ -15,23 +15,23 @@
  */
 package io.micronaut.openapi.annotation;
 
-import io.swagger.v3.oas.annotations.security.SecurityRequirement;
-import io.swagger.v3.oas.annotations.tags.Tag;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import static java.lang.annotation.RetentionPolicy.SOURCE;
 
 /**
  * The annotation to include Micronaut management endpoints.
  *
  * @author Denis Stepanov
  */
 @Documented
-@Retention(RUNTIME)
+@Retention(SOURCE)
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 public @interface OpenAPIManagement {
 

openapi/src/main/java/io/micronaut/openapi/annotation/OpenAPISecurity.java

@@ -15,23 +15,23 @@
  */
 package io.micronaut.openapi.annotation;
 
-import io.swagger.v3.oas.annotations.security.SecurityRequirement;
-import io.swagger.v3.oas.annotations.tags.Tag;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import static java.lang.annotation.RetentionPolicy.SOURCE;
 
 /**
  * The annotation to include Micronaut security endpoints.
  *
  * @author Denis Stepanov
  */
 @Documented
-@Retention(RUNTIME)
+@Retention(SOURCE)
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 public @interface OpenAPISecurity {
 

openapi/src/main/java/io/micronaut/openapi/introspections/MediaConfiguration.java

@@ -16,7 +16,7 @@
 package io.micronaut.openapi.introspections;
 
 import io.micronaut.core.annotation.Introspected;
-
+import io.micronaut.openapi.visitor.SimpleSchema;
 import io.swagger.v3.oas.models.media.ArraySchema;
 import io.swagger.v3.oas.models.media.BinarySchema;
 import io.swagger.v3.oas.models.media.BooleanSchema;
@@ -72,6 +72,7 @@
     Schema.class,
     StringSchema.class,
     UUIDSchema.class,
+    SimpleSchema.class,
     XML.class,
 })
 public class MediaConfiguration {