MicroProfile® OpenAPI 2.0 Release Review

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)