Package software.amazon.smithy.openapi.fromsmithy

Interface OpenApiMapper

All Known Subinterfaces:

ApiGatewayMapper

All Known Implementing Classes:

CheckForGreedyLabels, CheckForPrefixHeaders, CorsHttpIntegration, OpenApiJsonAdd, OpenApiJsonSubstitutions, RemoveEmptyComponents, RemoveUnusedComponents, SpecificationExtensionsMapper, UnsupportedTraits

public interface OpenApiMapper

Provides a plugin infrastructure used to hook into the Smithy to OpenAPI conversion process and map over the result.

The methods of a plugin are invoked by OpenApiConverter during the conversion of a model. There is no need to invoke these manually. Implementations may choose to leverage configuration options of the provided context to determine whether or not to enact the plugin.

Method Summary

Modifier and Type	Method	Description
default OpenApi	after(Context<? extends Trait> context, OpenApi openapi)	Updates an OpenApi object after it is built.
default void	before(Context<? extends Trait> context, OpenApi.Builder builder)	Updates an OpenApi.Builder before converting the model.
static OpenApiMapper	compose(List<OpenApiMapper> mappers)	Creates an OpenApiMapper that is composed of multiple mappers.
default byte	getOrder()	Gets the sort order of the plugin from -128 to 127.
default OperationObject	postProcessOperation(Context<? extends Trait> context, OperationShape shape, OperationObject operation, String httpMethodName, String path)	Updates an operation after invoking the plugin system on the contents of the operation (specifically, after updateOperation(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, software.amazon.smithy.openapi.model.OperationObject, java.lang.String, java.lang.String), updateParameter(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ParameterObject), updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject), updateResponse(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ResponseObject), and updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject)).
default void	updateDefaultSettings(Model model, OpenApiConfig config)	Sets default values on the OpenAPI configuration object.
default ObjectNode	updateNode(Context<? extends Trait> context, OpenApi openapi, ObjectNode node)	Modifies the Node/JSON representation of an OpenAPI object.
default OperationObject	updateOperation(Context<? extends Trait> context, OperationShape shape, OperationObject operation, String httpMethodName, String path)	Updates an operation before invoking the plugin system on the contents of the operation (specifically, before updateParameter(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ParameterObject), updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject), updateResponse(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ResponseObject), updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject), and postProcessOperation(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, software.amazon.smithy.openapi.model.OperationObject, java.lang.String, java.lang.String)).
default ParameterObject	updateParameter(Context<? extends Trait> context, OperationShape operation, String httpMethodName, String path, ParameterObject parameterObject)	Updates a parameter.
default PathItem	updatePathItem(Context<? extends Trait> context, String path, PathItem pathItem)	Updates a path item.
default RequestBodyObject	updateRequestBody(Context<? extends Trait> context, OperationShape operation, String httpMethodName, String path, RequestBodyObject requestBody)	Updates the request body of an operation.
default ResponseObject	updateResponse(Context<? extends Trait> context, OperationShape operation, String status, String httpMethodName, String path, ResponseObject response)	Updates a response object.
default Map<String,List<String>>	updateSecurity(Context<? extends Trait> context, Shape shape, SecuritySchemeConverter<? extends Trait> converter, Map<String,List<String>> requirement)	Updates a security requirement map.
default SecurityScheme	updateSecurityScheme(Context<? extends Trait> context, Trait authTrait, SecurityScheme securityScheme)	Updates a security scheme object.

Method Details

getOrder

default byte getOrder()

Gets the sort order of the plugin from -128 to 127.

Plugins are applied according to this sort order. Lower values are executed before higher values (for example, -128 comes before 0, comes before 127). Plugins default to 0, which is the middle point between the minimum and maximum order values.

Returns:

Returns the sort order, defaulting to 0.

updateDefaultSettings

default void updateDefaultSettings(Model model,
 OpenApiConfig config)

Sets default values on the OpenAPI configuration object.

Use this method and not before(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.openapi.model.OpenApi.Builder) to add default settings. Adding default settings in before() is possible, but might be too late in the process for those configuration changes to take effect.

Parameters:

model - Model being converted.

config - Configuration object to modify.

updateOperation

default OperationObject updateOperation(Context<? extends Trait> context,
 OperationShape shape,
 OperationObject operation,
 String httpMethodName,
 String path)

Updates an operation before invoking the plugin system on the contents of the operation (specifically, before updateParameter(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ParameterObject), updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject), updateResponse(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ResponseObject), updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject), and postProcessOperation(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, software.amazon.smithy.openapi.model.OperationObject, java.lang.String, java.lang.String)).

Parameters:

context - Conversion context.

shape - Operation being converted.

operation - OperationObject being built.

httpMethodName - The HTTP method of the operation.

path - The HTTP URI of the operation.

Returns:

Returns the updated operation object.

postProcessOperation

default OperationObject postProcessOperation(Context<? extends Trait> context,
 OperationShape shape,
 OperationObject operation,
 String httpMethodName,
 String path)

Updates an operation after invoking the plugin system on the contents of the operation (specifically, after updateOperation(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, software.amazon.smithy.openapi.model.OperationObject, java.lang.String, java.lang.String), updateParameter(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ParameterObject), updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject), updateResponse(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.ResponseObject), and updateRequestBody(software.amazon.smithy.openapi.fromsmithy.Context<? extends software.amazon.smithy.model.traits.Trait>, software.amazon.smithy.model.shapes.OperationShape, java.lang.String, java.lang.String, software.amazon.smithy.openapi.model.RequestBodyObject)).

Parameters:

context - Conversion context.

shape - Operation being converted.

operation - OperationObject being built.

httpMethodName - The HTTP method of the operation.

path - The HTTP URI of the operation.

Returns:

Returns the updated operation object.

updatePathItem

default PathItem updatePathItem(Context<? extends Trait> context,
 String path,
 PathItem pathItem)

Updates a path item.

Parameters:

context - Conversion context.

path - Path of the PathItem.

pathItem - Path item being converted.

Returns:

Returns the updated path item.

updateParameter

default ParameterObject updateParameter(Context<? extends Trait> context,
 OperationShape operation,
 String httpMethodName,
 String path,
 ParameterObject parameterObject)

Updates a parameter.

Parameters:

context - Conversion context.

operation - Smithy operation being converted.

httpMethodName - The HTTP method that this parameter is bound to.

path - The HTTP URI this parameter is bound to.

parameterObject - Parameter being updated.

Returns:

Returns the updated parameter.

updateRequestBody

default RequestBodyObject updateRequestBody(Context<? extends Trait> context,
 OperationShape operation,
 String httpMethodName,
 String path,
 RequestBodyObject requestBody)

Updates the request body of an operation.

Parameters:

context - Conversion context.

operation - Operation being converted.

httpMethodName - The HTTP method that this request is bound to.

path - The HTTP URI this request is bound to.

requestBody - Request body being updated.

Returns:

Returns the updated request body.

updateResponse

default ResponseObject updateResponse(Context<? extends Trait> context,
 OperationShape operation,
 String status,
 String httpMethodName,
 String path,
 ResponseObject response)

Updates a response object.

Parameters:

context - Conversion context.

operation - Operation shape being converted.

status - HTTP status of this response.

httpMethodName - The HTTP method that this response responds to.

path - The HTTP URI this response responds to.

response - Response object being updated.

Returns:

Returns the updated response object.

before

default void before(Context<? extends Trait> context,
 OpenApi.Builder builder)

Updates an OpenApi.Builder before converting the model.

Parameters:

context - Conversion context.

builder - OpenAPI builder to modify.

updateSecurityScheme

default SecurityScheme updateSecurityScheme(Context<? extends Trait> context,
 Trait authTrait,
 SecurityScheme securityScheme)

Updates a security scheme object.

Parameters:

context - Conversion context.

authTrait - Smithy authentication scheme trait.

securityScheme - Security scheme object to update.

Returns:

Returns the updated security scheme object. Return null to remove the scheme.

updateSecurity

default Map<String,List<String>> updateSecurity(Context<? extends Trait> context,
 Shape shape,
 SecuritySchemeConverter<? extends Trait> converter,
 Map<String,List<String>> requirement)

Updates a security requirement map.

The provided requirement Map will never be null or empty, but it may contain more than one key-value pair. A null or empty return value will cause the security requirement to be omitted from the converted shape.

Parameters:

context - Conversion context.

shape - Shape that is getting a security requirement (a service or operation).

converter - Security scheme converter.

requirement - Security scheme requirement to update.

Returns:

Returns the updated security requirement, a mapping of scheme to requirements.

after

default OpenApi after(Context<? extends Trait> context,
 OpenApi openapi)

Updates an OpenApi object after it is built.

Parameters:

context - Conversion context.

openapi - OpenAPI object to modify.

Returns:

Returns the updated OpenApi object.

updateNode

default ObjectNode updateNode(Context<? extends Trait> context,
 OpenApi openapi,
 ObjectNode node)

Modifies the Node/JSON representation of an OpenAPI object.

Parameters:

context - Conversion context.

openapi - OpenAPI object being converted to a node.

node - OpenAPI object node.

Returns:

Returns the updated ObjectNode.

compose

static OpenApiMapper compose(List<OpenApiMapper> mappers)

Creates an OpenApiMapper that is composed of multiple mappers.

Parameters:

mappers - Mappers to compose.

Returns:

Returns the composed mapper.