SmallRye OpenAPI

SmallRye OpenAPI is an implementation of Eclipse MicroProfile OpenAPI.

Instructions

Compile and install this project:

mvn clean install

Project structure

• core - The core OpenAPI code, independent of entry point dependencies.

• extension-jaxrs - The JAX-RS entry point. This module depends on JAX-RS and core.

• extension-spring - The Spring entry point. This module depends on Spring and core.

• extension-vertx - The Vert.x entry point. This module depends on Vert.x and core.

• implementation - Implementation of the Eclipse MicroProfile OpenAPI specification. This just pulls in Core and the JAX-RS extension .

• model - Base model classes used by core and extensions to represent an OpenAPI document

• testsuite - Test Suites and Data

  • coverage - Test coverage report aggregator for other modules

  • data - Quarkus application with tests to verify additional annotation scanning scenarios

  • extra - Extra integration tests not related to the TCK.

  • tck - Test suite to run the implementation against the Eclipse MicroProfile OpenAPI TCK.

• tools

  • gradle-plugin - Gradle plugin that creates the OpenAPI Schema on build.

  • maven-plugin - Maven plugin that creates the OpenAPI Schema on build.

  • model-apt - APT processor to generate model classes (in core) based on annotations (not for general-purpose use)

Links

• Project Homepage

• Eclipse MicroProfile OpenAPI

Configuration Extensions

Property Naming Strategy

mp.openapi.extensions.smallrye.property-naming-strategy

Define a naming strategy to be used globally for all schema properties. Set to one of the following:

• A standard JSON-B naming strategy (listed in jakarta.json.bind.config.PropertyNamingStrategy/javax.json.bind.config.PropertyNamingStrategy)

• A fully-qualified class name of an implementation of a JSON-B property naming strategy (jakarta.json.bind.config.PropertyNamingStrategy or javax.json.bind.config.PropertyNamingStrategy)

• A fully-qualified class name of an implementation of a Jackson property naming strategy base class (com.fasterxml.jackson.databind.PropertyNamingStrategies.NamingBase). Only the translate method is utilized.

Remove Unused Components (4.3.0)

mp.openapi.extensions.smallrye.remove-unused-components

Set to a comma-separated list of components types to enable automatic removal of unused components from /components in the OpenAPI model. Unused components will be removed following annotation scanning and after running all other OASFilter instances that may be configured. Disabled by default. Allowed values are the same as the keys for the components object. Specify * to enable removal of all unused components.

Note, this feature only supports simple component references with a format like /components/<type>/<name>. More complex references or links to sub-objects within a component (e.g. /components/parameters/MyParam/examples/MyExample) are not supported.

Specific components that are not referenced but should be retained in the final output should be identified using the retain directive with the x-smallrye-directives extension.

Removal of Unused Schemas (DEPRECATED)

mp.openapi.extensions.smallrye.remove-unused-schemas.enable

Deprecated - use mp.openapi.extensions.smallrye.remove-unused-components=schemas instead.

Set to true enable automatic removal of unused schemas from components/schemas in the OpenAPI model. Unused schemas will be removed following annotation scanning but prior to running any OASFilter that may be configured. Default value is false.

Automatic Schema Inheritance

mp.openapi.extensions.smallrye.auto-inheritance

Configures handling of schema inheritance. Allowed values include NONE (default), BOTH, and PARENT_ONLY.

• NONE disables automatic schema inheritance. Parent class properties will be includes in the properties map of each child class unless @Schema(allOf = { …​ }) has been specified on the child class.

• BOTH enables automatic schema inheritance by placing both the child and parent class within the child schema’s allOf property unless @Schema(allOf = { …​ }) has already been specified on the child class. BOTH processing can be selectively disabled on individual classes by setting @Schema(allOf = void.class) on the child class and no allOf will be set on the resulting schema - parent and child properties will be present in the child schema as if NONE were used.

• PARENT_ONLY enables automatic schema inheritance by placing only the parent class within the child schema’s allOf property unless @Schema(allOf = { …​ }) has already been specified on the child class. PARENT_ONLY processing can be selectively disabled on individual classes by setting @Schema(allOf = void.class) on the child class and no allOf will be set on the resulting schema - parent and child properties will be present in the child schema as if NONE were used.

Duplicate Operation ID Behavior

mp.openapi.extensions.smallrye.duplicateOperationIdBehavior

Set to FAIL to abort in case of duplicate operationIds, set to WARN to log warnings when the build encounters duplicate operationIds. Default value is WARN.

Maximum Static File Size

mp.openapi.extensions.smallrye.maximumStaticFileSize

Set this value in order to change the maximum threshold for processed static files, when generating model from them. If not set, it will default to 3 MB.

Merge Schema Examples

mp.openapi.extensions.smallrye.merge-schema-examples

Set this boolean value to disable the merging of the deprecated @Schema example property into the examples array introduced in OAS 3.1.0. If not set, it will default to true the deprecated example will be mapped to the examples array in the OpenAPI model.

Sorted Parameters

mp.openapi.extensions.smallrye.sorted-parameters.enable

Set this boolean value to enable or disable the sorting of parameter array entries during annotation scanning. When enabled (set to true), parameters will be order either by their order within a @Parameters annotation on an operation method or (in the absence of that annotation) by their $ref, in, and name attributes. When disabled (set to false), parameters will be in the order they are encountered in the Java code. If not set, it will default to true.

Generic Responses use default code

mp.openapi.extensions.smallrye.generic-response-use-default

Set this boolean value to enable the automatic use of the default response code for framework response types (e.g. Jakarta REST’s Response type) when no @APIResponse annotations have been used and the HTTP response code for an operation cannot be determined. When unset or false, the response code will be set to 200.

Operation ID Strategy

mp.openapi.extensions.smallrye.operationIdStrategy

Specify a strategy to be used globally for generating operation IDs when not specified via an annotation or static OpenAPI input. If not set, operation IDs will not be generated. Set to one of the following:

• METHOD (may result in duplicate operation IDs in an application where REST endpoint method names are not unique)

• CLASS_METHOD (may result in duplicate operation IDs in an application where REST endpoint simple class name + method names are not unique)

• PACKAGE_CLASS_METHOD

• A fully-qualified class name of an implementation of io.smallrye.openapi.api.OperationIdGenerator (as of 4.1.2, see JavaDoc)

YAML Alias Expansion (4.1.2)

mp.openapi.extensions.smallrye.yaml-alias-expansion.enable

Set this boolean value to enable or disable the expansion of YAML aliases when loading a static OpenAPI file. When enabled (set to true), aliases encountered in the YAML will expand to the value of the YAML node having an anchor of the same name (see more about YAML anchors and aliases in the YAML 1.1 specification). When disabled (set to false), aliases will not be expanded. If not set, it will default to true.

Scan Profiles

mp.openapi.extensions.smallrye.scan.profiles
mp.openapi.extensions.smallrye.scan.exclude.profiles

These properties are used together with the x-smallrye-profile extension to provide a way to limit which REST endpoints and associated resources are included in the OpenAPI model.

Extensions

x-smallrye-directives

The x-smallrye-directives extension is a string list/array that contains one or more directives used by smallrye-open-api to take or avoid various actions. The supported directives are listed below. All x-smallrye-directives extensions will be removed from the model before it is finalized.

retain

The retain directive is used together with the mp.openapi.extensions.smallrye.remove-unused-components property to indicate that a component should not be removed from the OpenAPI model even when it has no references from within the same model.

@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;
}

The same may also be done if using a static OpenAPI YAML or JSON to bootstrap the model.

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

x-smallrye-profile-{profileName}

The x-smallrye-profile-{profileName} extension provides a way to include or exclude an application’s resources in the OpenAPI model. When placed on a REST endpoint method, the extension name specifies a profile name that is used together with one of the scan profile configuration properties.

For example, given the following REST resource class and @Extension annotations, an OpenAPI document that excludes the /orders endpoint would be generated by specifying either mp.openapi.extensions.smallrye.scan.profiles=user or mp.openapi.extensions.smallrye.scan.exclude.profiles=order. Depending on your usage, either property maybe specified. All x-smallrye-profile-* extensions will be removed from the model before it is finalized.

import org.eclipse.microprofile.openapi.annotations.extensions.Extension;

@Path("/api")
public class MyResource {
    @Path("/users")
    @GET
    @Extension(name = "x-smallrye-profile-user", value = "")
    public List<UserDTO> listUsers() {
        // ...
    }

    @Path("/orders")
    @GET
    @Extension(name = "x-smallrye-profile-order", value = "")
    public List<OrderDTO> listOrders() {
        // ...
    }
}