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.

• Removal of unused schemas

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

  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 (as of 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.