Skip to content

smallrye/smallrye-open-api

Repository files navigation

badge Quality Gate Status License

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)

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.