Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/smallrye/smallrye-open-api

SmallRye implementation of Eclipse MicroProfile OpenAPI
https://github.com/smallrye/smallrye-open-api

microprofile openapi

Last synced: about 3 hours ago
JSON representation

SmallRye implementation of Eclipse MicroProfile OpenAPI

Awesome Lists containing this project

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



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

+

[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.



* Removal of unused schemas

+

[source%nowrap]

----

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

+

[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.



* 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`.



* 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

+

[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.