anchor.diff:  the JAX-RS and OpenAPI annotations from the application will be processed, further
   overriding any conflicting elements from the current model.
   
  +== OpenAPI Endpoint
  +
  +=== Overview
  +A fully processed and valid OpenAPI document must be available at the root
  +URL `/openapi`, as a `HTTP GET` operation.
  +
  +For example, `GET http://myHost:myPort/openapi`.
  +
  +This document represents the result of the applied <<Processing rules>>.
  +
  +=== Content format
  +The default `Content-Type` of the `/openapi` endpoint is `application/yaml`.
  +
  +Vendors must also support the type `application/json` if requested via the
  +`Accept` header.
  +
  +=== Query parameters
  +No query parameter are required for the `/openapi` endpoint.  However, one
  +suggested but optional query parameter for vendors to support is `format`,
  +where the value can be `json`, to facilate the toggle between the default `yaml`
  +format and `json` format.
  +
  +=== Context root behaviour
  +Vendors are required to ensure that the combination of each global https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject[server]
  +element and https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject[pathItem] element resolve to the absolute backend URL of that
  +particular path.  If that `pathItem` contains a `servers` element , then this
  +list of operation-level `server` elements replaces the global list of servers
  +for that particular `pathItem`.
  +
  +For example:  an application may have an `ApplicationPath` annotation with the
  +value of `/`, but is assigned the context root of `/myApp` during deployment. In
  +this case, the `server` elements (either global or operation-level) must either
  +end with `/myApp` or a corresponding proxy.  Alternatively it is valid, but discouraged, to
  +add that context root (`/myApp`) to every `pathItem` defined in that application.
  +
  +=== Multiple applications
  +
  +The 1.0 version of the MicroProfile OpenAPI specification does not define how
  +the `/openapi` endpoint may be partitioned in the event that the MicroProfile
  +runtime supports deployment of multiple applications. If an implementation wishes
  +to support multiple applications within a MicroProfile runtime, the semantics of
  +the `/openapi` endpoint are expected to be the logical AND of all the applications
  +in the runtime, which would imply merging multiple OpenAPI documents into a single
  +valid document (handling conflicting IDs and unique names).
   
   
   == Limitations
  
positive.code: the various <<Documentation Mechanisms>>, so that the implementing framework can
  perform a global replacement of the keys with the language-specific text that
  matches the `Accept-Language` request for the `/openapi` endpoint.  A cache of
  processed languages can be kept to improve performance. 
  
negative.code: = MicroProfile OpenAPI Specification
  
  == Introduction
  Exposing APIs has become an essential part of all modern applications.  At the
  center of this revolution known as the API Economy we find RESTful APIs, which can
  transform any application into language agnostic services that can be called from
  anywhere: on-premises, private cloud, public cloud, etc.
  
  For the clients and providers of these services to connect there needs to be a
  clear and complete contract.  Similar to the WSDL contract for legacy Web Services,
  the https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md[OpenAPI v3] specification is the contract for
  RESTful Services.
  
  This MicroProfile specification, called OpenAPI 1.0, aims to provide a set of Java
  interfaces and programming models which allow Java developers to natively produce
  OpenAPI v3 documents from their JAX-RS applications.
  
  == Architecture
  
  There are different ways to augment a JAX-RS application in order to produce an
  OpenAPI document, which are described in <<Documentation Mechanisms>>.  The picture
  below provides a quick overview of the different types of components that make up
  the MP OpenAPI specification:
  
  TODO: image
  
  The remaining sections of this specification will go into the details of each component.
  
  == Configuration
  
  Configuration of various parts of this specification is provided via the https://github.com/eclipse/microprofile-config[MicroProfile Config] mechanism,
  which means that vendors implementing the MP OpenAPI specification must also implement
  the MP Config specification.
  
  There are various ways to inject these configuration values into an MP OpenAPI
  framework, including the https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#default-configources[default ConfigSource] as well as
  https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#custom-configsources[custom ConfigSource].
  
  Vendors implementing the MP OpenAPI specification can also provide additional native
  ways for these configuration values to be injected into the framework
  (eg: via a server configuration file), as long as they also implement the MP Config
  specification.
  
  
  === List of configurable items
  
  Vendors must support all the <<Core configurations>> of this specification.
  Optionally, they may also support <<Vendor extensions>> that allow the configuration of
  framework-specific values for configurations that are affect implementation behavior.
  
  For convenience of vendors (and applications developers using custom ConfigSources),
  the full list of supported configuration keys is available as constants in the
  https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASConfig.java[OASConfig] class.
  
  ==== Core configurations
  
  The following is a list of configuration values that every vendor must support.
  
  [cols="1,4"]
  |===
  | Config key | Value description
  
  | `mp.openapi.model.reader` | Configuration property to specify the fully qualified name of the <<OASModelReader>> implementation.
  | `mp.openapi.filter` | Configuration property to specify the fully qualified name of the <<OASFilter>> implementation.
  | `mp.openapi.scan.disable`  |  Configuration property to disable annotation scanning.
  | `mp.openapi.scan.packages`  |  Configuration property to specify the list of packages to scan.
  | `mp.openapi.scan.classes`  |  Configuration property to specify the list of classes to scan.
  | `mp.openapi.servers`  |  Configuration property to specify the list of global servers that provide connectivity information.
  | `mp.openapi.servers.path.`   |  Prefix of the configuration property to specify an alternative list of servers to service all operations in a path.
  | `mp.openapi.servers.operation.` | Prefix of the configuration property to specify an alternative list of servers to service an operation.
  |===
  
  ==== Vendor extensions
  
  Vendors that wish to provide vendor-specific configuration via MP Config (instead
  of another native configuration framework) must use the prefix `mp.openapi.extensions`.
  
  == Documentation Mechanisms
  
  There are many different ways to provide input for the generation of the resulting
  OpenAPI document.
  
  The easiest way to get started is via the <<Annotations>>, since
  they augment (not replace) the existing JAX-RS annotations, meaning that application
  developers don't have to re-write the portions of the OpenAPI document that are
  already covered by the JAX-RS framework (eg: the HTTP method of an operation).
  
  Another way to document your APIs is via <<Static OpenAPI files>>.  This
  is specially adopted by enterprises that want to lock-in the contract of the API
  before any code is written.  In this case, we refer to the OpenAPI document as the
  "source of truth", by which the client and provider must abide to.
  
  The MP OpenAPI specification also provides a <<Programming model>> that allows
  application developers to provide a bootstrap or complete OpenAPI model tree.
  
  Lastly, we'll look at how to <<Filter>> different parts of the OpenAPI document
  during various processing stages.
  
  === Annotations
  
  Many of these annotations were derived from the https://github.com/swagger-api/swagger-core[Swagger Core] library, which
  allows for a mostly-mechanical transformation of applications that are using that
  library and wish to take advantage to the official MP OpenAPI interfaces.
  
  ==== Quick overview of annotations
  
  [cols="1,4"]
  |===
  | Annotation | Description
  |  |
  |  |
  |  |
  |===
  
  ==== Detailed usage of key annotations
  
  ===== Operation
  ===== APIResponse
  ===== Servers
  ===== Schema
  ===== And more.....
  
  === Static OpenAPI files
  ==== Location and formats
  
  === Programming model
  
  ==== OASModelReader
  
  ==== OASFactory
  
  
  === Filter
  
  ==== OASFilter
  
  
  
  === Processing rules
  
  The processed document available from the <<OpenAPI Endpoint>> is built from a variety of sources,
  which were outlined in the sub-headings of <<Documentation Mechanisms>>.  Vendors
  are required to process these different sources in the following order:
  
  