:OpenAPIVersion: 3.1
:MicroProfileOpenAPIVersion: 4.1

[[MicroProfile_OpenAPI_SmallRye]]
= MicroProfile OpenAPI Subsystem

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

The https://github.com/OAI/OpenAPI-Specification/blob/main/versions/{OpenAPIVersion}.0.md[OpenAPI specification] defines a contract for JAX-RS applications in the same way that WSDL defined a contract for legacy web services.
The https://download.eclipse.org/microprofile/microprofile-open-api-{MicroProfileOpenAPIVersion}/microprofile-openapi-spec-{MicroProfileOpenAPIVersion}.html[MicroProfile OpenAPI specification] defines a mechanism for generating an OpenAPI v3 document from a JAX-RS application as well as an API for customizing production of the document.

== Subsystem

The MicroProfile OpenAPI capability is provided by the microprofile-openapi-smallrye subsystem.
This subsystem is included in the default standalone-microprofile.xml configuration of the WildFly distribution.

You can also add the subsystem manually to any profile via the CLI:

[source,options="nowrap"]
----
[standalone@localhost:9990 /] /extension=org.wildfly.extension.microprofile.openapi-smallrye:add()

[standalone@localhost:9990 /] /subsystem=microprofile-openapi-smallrye:add()
----

== Configuration

The microprofile-openapi-smallrye subsystem obtains all of its configuration via MicroProfile Config.  Thus the subsystem itself defines no attributes.

In addition to the https://download.eclipse.org/microprofile/microprofile-open-api-{MicroProfileOpenAPIVersion}/microprofile-openapi-spec-{MicroProfileOpenAPIVersion}.html#_core_configurations[standard Open API configuration] properties, WildFly supports the following additional MicroProfile Config properties:

[cols="2,1,1,5"]
|===
|Property |Scope |Default |Description

|mp.openapi.extensions.enabled
|Deployment
|true
|Enables/disables registration of an OpenAPI endpoint.  Many users will want to parameterize this to selectively enable/disable OpenAPI in different environments.

|mp.openapi.extensions.path
|Deployment
|/openapi
|Used to customize the path of the OpenAPI endpoint.

|mp.openapi.extensions.server._server-name_.host._host-name_.auto-generate-servers +
mp.openapi.extensions.auto-generate-servers
|Global
|false
|Indicates whether to auto-generate Server URLs for this host if undefined by any application.

|mp.openapi.extensions.server._server-name_.host._host-name_.component-key-format +
mp.openapi.extensions.component-key-format
|Global
|%1$s%2$s
|Specifies the identifier format (using java.util.Formatter syntax) used generate distinct OpenAPI component keys for multiple applications.  Format accepts 2 parameters: context path, component name.

|mp.openapi.extensions.server._server-name_.host._host-name_.externalDocs.description +
mp.openapi.extensions.externalDocs.description
|Global
|_None_
|Defines the external documentation description of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.externalDocs.url +
mp.openapi.extensions.externalDocs.url
|Global
|_None_
|Defines the external documentation URL of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.contact.email +
mp.openapi.extensions.info.contact.email
|Global
|_None_
|Defines the contact email of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.contact.name +
mp.openapi.extensions.info.contact.name
|Global
|_None_
|Defines the contact name of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.contact.url +
mp.openapi.extensions.info.contact.url
|Global
|_None_
|Defines the contact url of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.description +
mp.openapi.extensions.info.description
|Global
|_None_
|Defines the description of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.license.name +
mp.openapi.extensions.info.license.name
|Global
|_None_
|Defines the license name of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.license.identifier +
mp.openapi.extensions.info.license.identifier
|Global
|_None_
|Defines the license identifier of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.license.url +
mp.openapi.extensions.info.license.url
|Global
|_None_
|Defines the license URL of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.summary +
mp.openapi.extensions.info.summary
|Global
|_None_
|Defines the summary of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.termsOfService +
mp.openapi.extensions.info.termsOfService
|Global
|_None_
|Defines the terms of service of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.title +
mp.openapi.extensions.info.title
|Global
|_None_
|Defines the title of the OpenAPI document provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.info.version +
mp.openapi.extensions.info.version
|Global
|_None_
|Defines the application API version provided by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.jsonSchemaDialect +
mp.openapi.extensions.jsonSchemaDialect
|Global
|_None_
|Defines the JSON schema dialect used by this host.

|mp.openapi.extensions.server._server-name_.host._host-name_.version +
mp.openapi.extensions.version
|Global
|_None_
|Defines the OpenAPI specification version used by this host.

|===

e.g. `/META-INF/microprofile-config.properties`:
[source,options="nowrap"]
---- 
mp.openapi.extensions.enabled=${microprofile.openapi.enabled}
mp.openapi.extensions.path=/swagger
----

== HTTP/S Endpoint

The MicroProfile OpenAPI specification defines an HTTP endpoint that serves an OpenAPI {OpenAPIVersion} document describing the REST endpoints for the host.
The OpenAPI endpoint is registered using the configured path (e.g. http://localhost:8080/openapi) local to the root of the host associated with a given deployment.

[NOTE]
When the OpenAPI endpoint for a given host documents _a single_ JAX-RS deployment, the title and description of the OpenAPI document are obtained from the <display-name/> and <description/> elements, respectively, from the web application deployment descriptor (e.g. web.xml), if otherwise unspecified.
When the OpenAPI endpoint for a given host documents _multiple_ JAX-RS deployments, any discordant 'info' or 'externalDocs' OpenAPI document properties will be sourced from the MicroProfile config properties prefixed by 'mp.openapi.extensions.server._server-name_.host._host-name_', where 'server-name' and 'host-name' identify the virtual host as defined within the Undertow subsystem.
To avoid the possibility of conflicting values, these are best defined globally, rather than per application, e.g. '-Dmp.openapi.extensions.server.default-server.host.default-host.info.version=1.0'.

By default, the OpenAPI endpoint returns a YAML document.
Alternatively, a JSON document can be requested via an `Accept` HTTP header, or a `format` query parameter.

e.g.

[source,shell,subs="attributes+"]
----
$ curl -v http://localhost:8080/openapi?format=JSON
< HTTP/1.1 200 OK
...
{"openapi": "{OpenAPIVersion}.0" ... }


$ curl -v -H'Accept: application/json' http://localhost:8080/openapi
< HTTP/1.1 200 OK
...
{"openapi": "{OpenAPIVersion}.0" ... }
----

If the Undertow server/host of a given application defines an HTTPS listener, then the OpenAPI document will also be available via HTTPS, e.g. https://localhost:8443/openapi

== Component Reference

The MicroProfile OpenAPI implementation is provided by the SmallRye OpenAPI project.

****

* https://microprofile.io/project/eclipse/microprofile-open-api[MicroProfile OpenAPI]
* http://github.com/smallrye/smallrye-open-api/[SmallRye OpenAPI]

****

NOTE: References in this document to Java API for RESTful Web Services (JAX-RS) refer to Jakarta RESTful Web Services unless otherwise noted.
