From 7464af5f945ffd0c5b96679bc3ec70813ff0aaec Mon Sep 17 00:00:00 2001 From: Manasi Gandhi Date: Tue, 7 Jan 2020 12:48:19 -0500 Subject: [PATCH] Update 10 --- ref/general/mp-openapi.adoc | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/ref/general/mp-openapi.adoc b/ref/general/mp-openapi.adoc index 8c642574b4..5f2618854f 100644 --- a/ref/general/mp-openapi.adoc +++ b/ref/general/mp-openapi.adoc @@ -23,15 +23,35 @@ JAX-RS annotations are processed by default with MP OpenAPI. You can augment the Vendors must process all the relevant JAX-RS annotations, like @Path and @Consumes, and Java objects used as input or output to JAX-RS operations. Developers can deploy their existing JAX-RS application into a MP OpenAPI vendor and check out the output from `/openapi`. Annotations like @Callback, @Components, @ParameterIn, and more are found in the Eclipse OpenAPI annotations package . For an overview of annotation, see https://download.eclipse.org/microprofile/microprofile-open-api-1.0/microprofile-openapi-spec.html#_quick_overview_of_annotations. - used. See .. for a Quick overview of annotations (add link). + +When the same annotation is used on a class and a method, the values from the method instance take precedence for that particular method, for example, @Server and @Tag annotations. The annotation values from the method’s parameters take precedence over corresponding annotation values from the method itself, for example, @Parameter and @RequestBody. The @Schema annotation has a complex set of possible combinations. It can be placed on POJOs and referenced from many other annotations. + +For examples of annotations, see link:https://github.com/eclipse/microprofile-open-api/wiki/Annotation-Samples[Annotation Samples] + == Static OpenAPI files Take the initial output from `/openapi` as a starting point to document your APIs with Static OpenAPI files. The static files can also be written before any code, which is an approach often adopted by enterprises that want to lock-in the contract of the API. The OpenAPI document is referred as the "source of truth" in this case, by which the client and provider must abide. +You can use a static OpenAPI file in YAML format or JSON format. + +For examples of Static OpenAPI files, see link:https://github.com/eclipse/microprofile-open-api/wiki/Static-File-Samples[Static File Samples]. + == Programming model -Use the API interfaces to provide a bootstrap OpenAPI model tree. +You can provide OpenAPI elements via Java POJOs. For a complete set of models see, link:https://github.com/eclipse/microprofile-open-api/tree/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations[org.eclipse.microprofile.openapi.models] package. + +Use link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java[OASFactory] to create all the elements of an OpenAPI tree, and the link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASModelReader.java[OASModelReader] interface to bootstrap the OpenAPI model tree used by the processing framework. + +For examples of OASModelReader, see link:https://github.com/eclipse/microprofile-open-api/wiki/OASModelReader-Samples[OASModelReader Samples]. == Filter -Sometimes application developers might need to update or remove certain elements and fields of the OpenAPI document. This is done via a filter, which is called once after all other documentation mechanisms have completed. +With link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFilter.java[OASFilter], you can receive callbacks for various key OpenAPI elements. To use it, create an implementation of the interface and register it using the `mp.openapi.filter` configuration key, where the value is the fully qualified name of the filter class. + +For examples of OASFilter, see link:https://github.com/eclipse/microprofile-open-api/wiki/OASFilter-Samples[OASFilter Samples]. + +==OpenAPI UI + +The native OpenAPI UI is value-add from Open Liberty is that ships out of the box. This UI is built from the link:https://github.com/swagger-api/swagger-ui[Open Source Swagger UI] and renders the generated `/openapi` document into a user friendly page. It has the ability to `Try out` each endpoint, making an invocation to the back-end straight from the UI. + +The UI, available from the endpoint `/openapi/ui` can also be link:https://www.ibm.com/support/knowledgecenter/en/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/twlp_api_mpopenapi_custom.html[customized].