anchor.diff:  = 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
   
  -== 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).
  +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
  -=== Configuration approaches
  -=== Vendor specific configuration
  +
  +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
   
  -==== Table of annotations
  -==== Usage
  +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
  +===== APIResponse
   ===== Servers
   ===== Schema
   ===== And more.....
   
  -=== Models
  -==== How to build OpenAPI model in Java™
  -
  -=== Filter/Interceptor
  -==== Filter mechanics
  -
   === Static OpenAPI files
   ==== Location and formats
  -==== Precedence
  +
  +=== Programming model
  +
  +==== OASModelReader
  +
  +==== OASFactory
  +
  +
  +=== Filter
  +
  +==== OASFilter
  +
  +
   
   === Processing rules
   
  -The processed document available from `/openapi` is built from a variety of sources,
  +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:
   
  
positive.code: the JAX-RS and OpenAPI annotations from the application will be processed, further
  overriding any conflicting elements from the current model.
  
  
  
  == Limitations
  
negative.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.
  