SmallRye OpenAPI

Use the operationIdStrategy property to control how operationId is generated for OpenAPI operations. This helps minimize collision risks.

Available strategies:

• METHOD: Uses the method name.
• CLASS_METHOD: Uses the class name and method name.
• PACKAGE_CLASS_METHOD: Uses the fully qualified class name and method name.

SmallRye OpenAPI UI allows you to integrate a Swagger UI into your project to visualize and interact with your OpenAPI documentation. Once included, the UI is automatically available at the /openapi-ui endpoint.

Note: This extension expects your OpenAPI specification to be available at the /openapi endpoint.

<dependency>
    <groupId>io.smallrye</groupId>
    <artifactId>smallrye-open-api-ui</artifactId>
    <version>xyz</version>
    <scope>runtime</scope>
</dependency>

The retain directive allows you to prevent the automatic removal of unreferenced components or tags when using mp.openapi.extensions.smallrye.remove-unused-components or mp.openapi.extensions.smallrye.remove-unused-tags.enable.

Using in Java: Apply the retain directive via the @Extension annotation on the @Schema annotation.

@Schema(
    extensions = @Extension(name = "x-smallrye-directives", value = "retain,other-directive"),
    comment = "This class uses the `retain` directive to avoid removal")
class MyUnusedBean {
    String name;
    Integer age;
}

Using in YAML/JSON: Add the x-smallrye-directives key to the component definition.

openapi: 3.1.0
components:
  schemas:
    MyUnusedBean:
      comment: This class uses the `retain` directive to avoid removal
      x-smallrye-directives:
        - retain
        - other-directive

You can make the plugin available to your build without installing it to a repository by using Gradle's includeBuild feature.

1. Configure settings: Add the following snippet to your Gradle project's settings.gradle[.kts], replacing FULL_PATH_TO_tools/gradle-plugin with the actual absolute path to the plugin source:

   includeBuild("FULL_PATH_TO_tools/gradle-plugin")

2. Apply the plugin: In your target project's build.gradle[.kts], apply the plugin using the standard mechanism:

   plugins {
       id("io.smallrye.openapi")
   }

Specify a global strategy for generating operationIds when they are not provided via annotations or static input using mp.openapi.extensions.smallrye.operationIdStrategy.

Allowed Values:

• METHOD: Uses the REST endpoint method name (may cause duplicates if method names are not unique across the app).
• CLASS_METHOD: Uses the simple class name + method name (may cause duplicates if class/method combinations are not unique).
• PACKAGE_CLASS_METHOD: Uses the package + class + method name.
• Custom Implementation: A fully-qualified class name of an implementation of io.smallrye.openapi.api.OperationIdGenerator.

Enable automatic removal of unused tags from the top-level tags array by setting mp.openapi.extensions.smallrye.remove-unused-tags.enable to true.

• Definition of Unused: A tag is considered unused if it is not referenced by any operation in the paths section.
• Behavior: Unused tags are removed after annotation scanning and after all configured OASFilter instances have run.
• Retention: To keep an unreferenced tag, use the retain directive within the x-smallrye-directives extension.

Control how schema inheritance is handled in the OpenAPI model using mp.openapi.extensions.smallrye.auto-inheritance.

Allowed Values:

• NONE (default): Disables automatic inheritance. Parent class properties are included in the child class properties map unless @Schema(allOf = { ... }) is explicitly specified on the child.
• BOTH: Enables automatic inheritance by placing both the child and parent class within the child schema's allOf property, unless @Schema(allOf = { ... }) is already specified.
• PARENT_ONLY: Enables automatic inheritance by placing only the parent class within the child schema's allOf property, unless @Schema(allOf = { ... }) is already specified.

Disabling for specific classes: To disable automatic inheritance for a specific class, set @Schema(allOf = void.class) on that class.

You can control how operationId values are generated using the getOperationIdStrategy() method. The available strategies are defined in the OperationIdStrategy class:

• METHOD: Uses the resource method's name.
• CLASS_METHOD: Uses the resource class's simple name and the resource method's name.
• PACKAGE_CLASS_METHOD: Uses the resource class's fully-qualified name and the resource method's name.

// Example of the strategy names used in configuration
String strategy = OpenApiConfig.OperationIdStrategy.CLASS_METHOD;