Package software.amazon.smithy.openapi.fromsmithy

Interface OpenApiProtocol<T extends Trait>

Type Parameters:

T - Type of Smithy protocol to convert.

All Known Implementing Classes:

AwsRestJson1Protocol

public interface OpenApiProtocol<T extends Trait>

An OpenAPI protocol is used to convert a Smithy protocol into HTTP-specific bindings.

Instances of OpenApiProtocol are discovered using SPI and matched with configuration settings based on the result of matching a protocol against getProtocolType().

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	OpenApiProtocol.Operation	Represents an operation entry to add to an OpenApi.Builder.

Method Summary

Modifier and Type	Method	Description
java.util.Optional<OpenApiProtocol.Operation>	createOperation(Context<T> context, OperationShape operation)	Creates an operation entry, including the method, URI, and operation object builder.
default java.lang.String	getOperationMethod(Context<T> context, OperationShape operation)	Gets the HTTP method of an operation.
default java.lang.String	getOperationResponseStatusCode(Context<T> context, ToShapeId operationOrError)	Gets the response status code of an operation or error shape.
default java.lang.String	getOperationUri(Context<T> context, OperationShape operation)	Gets the URI of an operation.
default java.util.Set<java.lang.String>	getProtocolRequestHeaders(Context<T> context, OperationShape operationShape)	Gets the unmodeled protocol-specific HTTP headers of a request that are considered significant for the provided operation.
default java.util.Set<java.lang.String>	getProtocolResponseHeaders(Context<T> context, OperationShape operationShape)	Gets the unmodeled protocol-specific HTTP headers of a response that are considered significant for the provided operation.
java.lang.Class<T>	getProtocolType()	Gets the protocol type that this converter handles.
default void	updateDefaultSettings(Model model, OpenApiConfig config)	Sets protocol-specific default values on the OpenAPI configuration object.

Method Detail

getProtocolType

java.lang.Class<T> getProtocolType()

Gets the protocol type that this converter handles.

Returns:

Returns the shape ID.

updateDefaultSettings

default void updateDefaultSettings(Model model,
                                   OpenApiConfig config)

Sets protocol-specific default values on the OpenAPI configuration object.

Parameters:

model - Model being converted.

config - Configuration object to modify.

createOperation

java.util.Optional<OpenApiProtocol.Operation> createOperation(Context<T> context,
                                                              OperationShape operation)

Creates an operation entry, including the method, URI, and operation object builder. The returned operation object builder should contain protocol-specific fields of an OpenAPI Operation object, such as: [parameters, requestBody, responses] and [examples for any of the above, contained by respective objects that the example values are for]. The returned operation object builder should not contain protocol-agnostic fields of an OpenAPI Operation object, such as: tags, summary, description, externalDocs, deprecated, security.

The operation is returned as an empty Optional if the operation is not supported by the protocol. This method should make calls to getOperationUri(software.amazon.smithy.openapi.fromsmithy.Context<T>, software.amazon.smithy.model.shapes.OperationShape) and getOperationMethod(software.amazon.smithy.openapi.fromsmithy.Context<T>, software.amazon.smithy.model.shapes.OperationShape) when creating the Operation object.

Parameters:

context - The build context.

operation - The operation shape to create.

Returns:

Returns the optionally created operation entry.

getOperationUri

default java.lang.String getOperationUri(Context<T> context,
                                         OperationShape operation)

Gets the URI of an operation.

The default implementation will attempt to get the HTTP URI defined by the HttpTrait trait. If no HTTP trait can be found, the default implementation will throw an exception.

Parameters:

context - The build context.

operation - The operation to get the URI of.

Returns:

Returns the operation URI.

getOperationMethod

default java.lang.String getOperationMethod(Context<T> context,
                                            OperationShape operation)

Gets the HTTP method of an operation.

The default implementation will attempt to get the HTTP method defined by the HttpTrait trait. If no HTTP trait can be found, the default implementation will throw an exception.

Parameters:

context - The build context.

operation - The operation to get the method of.

Returns:

Returns the method.

getOperationResponseStatusCode

default java.lang.String getOperationResponseStatusCode(Context<T> context,
                                                        ToShapeId operationOrError)

Gets the response status code of an operation or error shape.

The default implementation will attempt to use HTTP binding traits to determine the HTTP status code of an operation or error structure.

Parameters:

context - The build context.

operationOrError - Operation or error shape ID.

Returns:

Returns the status code as a string.

getProtocolRequestHeaders

default java.util.Set<java.lang.String> getProtocolRequestHeaders(Context<T> context,
                                                                  OperationShape operationShape)

Gets the unmodeled protocol-specific HTTP headers of a request that are considered significant for the provided operation.

These protocol specific headers are not automatically added to requests, but are used when integrating with things like CORS.

Parameters:

context - OpenAPI context

operationShape - Smithy operation

Returns:

Returns a set of header names.

getProtocolResponseHeaders

default java.util.Set<java.lang.String> getProtocolResponseHeaders(Context<T> context,
                                                                   OperationShape operationShape)

Gets the unmodeled protocol-specific HTTP headers of a response that are considered significant for the provided operation.

These protocol specific headers are not automatically added to responses, but are used when integrating with things like CORS.

Parameters:

context - OpenAPI context

operationShape - Smithy operation

Returns:

Returns a set of header names.