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().

  • Method Details

    • getProtocolType

      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

      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 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 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 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 Set<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 Set<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.