# smallrye-open-api **Repository Path**: mirrors_smallrye/smallrye-open-api ## Basic Information - **Project Name**: smallrye-open-api - **Description**: SmallRye implementation of Eclipse MicroProfile OpenAPI - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-09-25 - **Last Updated**: 2026-03-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README :microprofile-open-api: https://github.com/eclipse/microprofile-open-api/ image:https://github.com/smallrye/smallrye-open-api/workflows/SmallRye%20Build/badge.svg?branch=main[link=https://github.com/smallrye/smallrye-open-api/actions?query=workflow%3A%22SmallRye+Build%22] image:https://sonarcloud.io/api/project_badges/measure?project=smallrye_smallrye-open-api&metric=alert_status["Quality Gate Status", link="https://sonarcloud.io/dashboard?id=smallrye_smallrye-open-api"] image:https://img.shields.io/github/license/thorntail/thorntail.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"] = SmallRye OpenAPI :source-highlighter: rouge SmallRye OpenAPI is an implementation of {microprofile-open-api}[Eclipse MicroProfile OpenAPI]. == Instructions Compile and install this project: [source,bash] ---- mvn clean install ---- === Project structure * link:core[core] - The core OpenAPI code, independent of entry point dependencies. * link:extension-jaxrs[extension-jaxrs] - The JAX-RS entry point. This module depends on JAX-RS and core. * link:extension-spring[extension-spring] - The Spring entry point. This module depends on Spring and core. * link:extension-vertx[extension-vertx] - The Vert.x entry point. This module depends on Vert.x and core. * link:implementation[implementation] - Implementation of the Eclipse MicroProfile OpenAPI specification. This just pulls in Core and the JAX-RS extension . * link:model[model] - Base model classes used by core and extensions to represent an OpenAPI document * link:testsuite[testsuite] - Test Suites and Data ** link:testsuite/coverage[coverage] - Test coverage report aggregator for other modules ** link:testsuite/data[data] - Quarkus application with tests to verify additional annotation scanning scenarios ** link:testsuite/extra[extra] - Extra integration tests not related to the TCK. ** link:testsuite/tck[tck] - Test suite to run the implementation against the Eclipse MicroProfile OpenAPI TCK. * link:tools[tools] ** link:tools/gradle-plugin[gradle-plugin] - Gradle plugin that creates the OpenAPI Schema on build. ** link:tools/maven-plugin[maven-plugin] - Maven plugin that creates the OpenAPI Schema on build. ** link:tools/model-apt[model-apt] - APT processor to generate model classes (in core) based on annotations (not for general-purpose use) === Links * http://github.com/smallrye/smallrye-open-api/[Project Homepage] * {microprofile-open-api}[Eclipse MicroProfile OpenAPI] === Configuration Extensions [#property-naming-strategy] ==== Property Naming Strategy [source%nowrap] ---- 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] ==== Remove Unused Components (4.3.0) [source%nowrap] ---- 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 https://spec.openapis.org/oas/v3.1.0.html#components-object[components object]. Specify `*` to enable removal of all unused components. Note, this feature only supports simple component references with a format like `#/components//`. 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 <> directive with the <> extension. [#remove-unused-schemas] ==== Removal of Unused Schemas (DEPRECATED) [source%nowrap] ---- 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`. [#auto-inheritance] ==== Automatic Schema Inheritance [source%nowrap] ---- 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. [#duplicateOperationIdBehavior] ==== Duplicate Operation ID Behavior [source%nowrap] ---- 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`. [#maximumStaticFileSize] ==== Maximum Static File Size [source%nowrap] ---- 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] ==== Merge Schema Examples [source%nowrap] ---- 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] ==== Sorted Parameters [source%nowrap] ---- 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-response-use-default] ==== Generic Responses use `default` code [source%nowrap] ---- mp.openapi.extensions.smallrye.generic-response-use-default ---- Set this boolean value to enable the automatic use of the https://spec.openapis.org/oas/v3.1.0.html#responses-object[`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`. [#operationIdStrategy] ==== Operation ID Strategy [source%nowrap] ---- 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, https://javadoc.io/doc/io.smallrye/smallrye-open-api-core/latest/io/smallrye/openapi/api/OperationIdGenerator.html[see JavaDoc]) [#yaml-alias-expansion] ==== YAML Alias Expansion (4.1.2) [source%nowrap] ---- 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 https://yaml.org/spec/1.1/#id863390[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] ==== Scan Profiles [source%nowrap] ---- mp.openapi.extensions.smallrye.scan.profiles mp.openapi.extensions.smallrye.scan.exclude.profiles ---- These properties are used together with the <> extension to provide a way to limit which REST endpoints and associated resources are included in the OpenAPI model. === Extensions [#x-smallrye-directives] ==== 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. [#x-smallrye-directives-retain] ===== 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. [source%nowrap, java] ---- @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. [source%nowrap, yaml] ---- 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] ==== 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 <> 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. [source%nowrap, java] ---- 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 listUsers() { // ... } @Path("/orders") @GET @Extension(name = "x-smallrye-profile-order", value = "") public List listOrders() { // ... } } ----