OpenAPI 2.0

A full list of changes delivered in the 2.0 release can be found at MicroProfile OpenAPI 2.0 Milestone.

1. Incompatible Changes

Model interfaces that were deprecated in 1.1 have been removed:
- Scopes - this interface was replaced with Map<String, ServerVariable> because it did not need to be extensible (328)
- ServerVariables - this interface was replaced with Map<String, ServerVariable> because it did not need to be extensible (245)
Model interfaces that are not extensible no longer extend java.util.Map:
- APIResponses (248)
- Callback (248)
- Content (248)
- Path (248)
- SecurityRequirement (248)
Methods on model interfaces that were deprecated) in 1.1 have been removed:
- APIResponses
  - addApiResponse(String name, APIResponse apiResponse) - use addAPIResponse(String, APIResponse) instead (229)
  - get(Object key) - use getAPIResponse(String) instead (248)
  - containsKey(Object key) - use hasAPIResponse(String) instead (248)
  - put(String key, PathItem value) - use addAPIResponse(String, APIResponse) instead (248)
  - putAll(Map<? extends String, ? extends PathItem> m) - use setAPIResponses(Map) instead (248)
  - remove(Object key) - use removeAPIResponse(String) instead (248)
- Callback
  - get(Object key) - use getPathItem(String) instead (248)
  - containsKey(Object key) - use hasPathItem(String) instead (248)
  - put(String key, PathItem value) - use addPathItem(String, PathItem) instead (248)
  - putAll(Map<? extends String, ? extends PathItem> m) - use setPathItems(Map) instead (248)
  - remove(Object key) - use removePathItem(String) instead (248)
- Content
  - get(Object key) - use getMediaType(String) instead (248)
  - containsKey(Object key) - use hasMediaType(String) instead (248)
  - put(String key, PathItem value) - use addMediaType(String, MediaType) instead (248)
  - putAll(Map<? extends String, ? extends PathItem> m) - use setMediaTypes(Map) instead (248)
  - remove(Object key) - use removeMediaType(String) instead (248)
- OASFactory
  - createScopes - use Map<String, String> for scopes instead (328)
  - createServerVariables - use use Map<String, ServerVariable> for server variables instead (245)
- OAuthFlow
  - setScopes(Scopes scopes) - use setScopes(Map) instead (328)
  - scopes(Scopes scopes) - use scopes(Map) instead (328)
- OpenAPI
  - path(String name, PathItem path) - use Paths#addPathItem(String, PathItem) on OpenAPI#getPaths instead (247)
- Path
  - get(Object key) - use getPathItem(String) instead (248)
  - containsKey(Object key) - use hasPathItem(String) instead (248)
  - put(String key, PathItem value) - use addPathItem(String, PathItem) instead (248)
  - putAll(Map<? extends String, ? extends PathItem> m) - use setPathItems(Map) instead (248)
  - remove(Object key) - use removePathItem(String) instead (248)
- PathItem
  - readOperations - use Map#values() on PathItem#getOperations() instead (256)
  - readOperationsMap - use getOperations() instead (256)
- Schema
  - getAdditionalProperties - use getAdditionalPropertiesSchema() or getAdditionalPropertiesBoolean() instead (257, 281)
  - setAdditionalProperties(Schema additionalProperties) - use setAdditionalPropertiesSchema(Schema) instead (257, 281)
  - setAdditionalProperties(Boolean additionalProperties) - use setAdditionalPropertiesBoolean(Boolean) instead (257, 281)
  - additionalProperties(Schema additionalProperties) - use additionalPropertiesSchema(Schema) instead (257, 281)
  - additionalProperties(Boolean additionalProperties) - use additionalPropertiesBoolean(Boolean) instead (257, 281)
- SecurityRequirement
  - get(Object key) - use getScheme(String) instead (248)
  - containsKey(Object key) - use hasScheme(String) instead (248)
  - put(String key, PathItem value) - use addScheme(String, List) instead (248)
  - putAll(Map<? extends String, ? extends PathItem> m) - use setSchemes(Map) instead (248)
  - remove(Object key) - use removeScheme(String) instead (248)
- Server
  - setVariables(ServerVariables variables) - use setVariables(Map) instead (245)
  - variables(ServerVariables variables) - use variables(Map) instead (245)

2. API/SPI Changes

The @SchemaProperty annotation has been added to allow the properties for a schema to be defined inline. (360). For example:

@Schema(properties={
@SchemaProperty(name="creditCard", required=true),
@SchemaProperty(name="departureFlight", description="The departure flight information."),
@SchemaProperty(name="returningFlight")
})

The @RequestBodySchema annotation has been added to provide a shorthand mechanism to specify the schema for a request body (363). For example:

@RequestBodySchema(MyRequestObject.class)

The @APIResponseSchema annotation has been added to provide a shorthand mechanism to specify the schema for a response body (363). For example:

@APIResponseSchema(MyResponseObject.class)

The mp.openapi.schema.* MicroProfile Config property has been added to allow the schema for a specific class to be specified. This property would typically be used in cases where the application developer does not have access to the source code of a class (364). For example:

mp.openapi.schema.java.time.Instant = { \
"name": "EpochSeconds", \
"type": "number", \
"format": "int64", \
"title": "Epoch Seconds", \
"description": "Number of seconds from the epoch of 1970-01-01T00:00:00Z" \
}

3. Functional Changes

Getter methods on model interfaces that return a list or map now return a copy of the list/map containing the same items. This list/map CAN be immutable. (240)
Setter methods on model interfaces that take a list or a map as a parameter MUST not use the list/map instance directly (284)

4. Other Changes

JavaDoc updates to clarify the behaviour of getter methods on model interfaces that return a list or map ((240), 288)
TCK updates updates to verify that getter methods on model interfaces return a list or map, return a copy of underlying collection ((240), 288)

Release Date:

Sunday, December 20, 2020

Review:

OpenAPI 2.0 Release Review

Release Type:

Major release (API breakage)

MicroProfile® OpenAPI 2.0

Primary tabs

1. Incompatible Changes

2. API/SPI Changes

3. Functional Changes

4. Other Changes