[[MicroProfile_OpenAPI_SmallRye]]
= MicroProfile OpenAPI Subsystem Configuration

Support for https://microprofile.io/project/eclipse/microprofile-open-api[Eclipse MicroProfile OpenAPI] is provided by
 the _microprofile-openapi-smallrye_ subsystem.

[[required-extension-microprofile-openapi-smallrye]]
== Required Extension

This extension is included in the standalone configurations included in the
WildFly distribution.

You can also add the extension to a configuration without it either by adding
an `<extension module="org.wildfly.extension.microprofile.openapi-smallrye"/>`
element to the xml or by using the following CLI operation:

[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 subsytem 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-1.1.2/microprofile-openapi-spec.html#_core_configurations[standard Open API configuration] properties, WildFly supports the following additional MicroProfile Config properties:

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

|mp.openapi.extensions.enabled
|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
|/openapi
|Used to customize the path of the OpenAPI endpoint.

|mp.openapi.extensions.servers.relative
|true
|Indicates whether auto-generated Server records are absolute or relative to the location of the OpenAPI endpoint.  If absolute, WildFly will generate Server records including the protocols, hosts, and ports at which the given deployment is accessible.

|===

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

== HTTP Endpoints

The MicroProfile OpenAPI specification defines an HTTP endpoint at path `/openapi` to retrieve
the OpenAPI 3.0 document in YAML (the default) and JSON formats. The OpenAPI HTTP endpoint
is accessible by default at http://localhost:8080/openapi[http://localhost:8080/openapi]. If the
default YAML format is not desired, JSON may be used by providing either an HTTP `Accept` header
value `application/json` or a query parameter `format` with value `JSON`.

[source,shell]
----
$ curl -v http://localhost:8080/openapi?format=application/json
< HTTP/1.1 200 OK
...
{"openapi": "3.0.1" ... }


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

----

== Component Reference

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

****

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

****