Class OpenApiConfig

java.lang.Object
software.amazon.smithy.jsonschema.JsonSchemaConfig
software.amazon.smithy.openapi.OpenApiConfig

public class OpenApiConfig extends JsonSchemaConfig
"openapi" smithy-build plugin configuration settings.
  • Constructor Details

    • OpenApiConfig

      public OpenApiConfig()
  • Method Details

    • getProtocol

      public ShapeId getProtocol()
    • setProtocol

      public void setProtocol(ShapeId protocol)
      Sets the protocol shape ID to use when converting Smithy to OpenAPI.

      For example, aws.protocols#restJson1.

      Smithy will try to match the provided protocol name with an implementation of OpenApiProtocol registered with a service provider implementation of Smithy2OpenApiExtension.

      This property is required if a service supports multiple protocols.

      Parameters:
      protocol - The protocol shape ID to use.
    • getDefaultBlobFormat

      public String getDefaultBlobFormat()
    • setDefaultBlobFormat

      public void setDefaultBlobFormat(String defaultBlobFormat)
      Sets the default OpenAPI format property used when converting blob shapes in Smithy to strings in OpenAPI.

      Defaults to "byte", meaning Base64 encoded.

      Parameters:
      defaultBlobFormat - Default blob OpenAPI format to use.
    • getTags

      public boolean getTags()
    • setTags

      public void setTags(boolean tags)
      Sets whether or not to include Smithy tags in the result as OpenAPI tags.
      Parameters:
      tags - Set to true to enable tags.
    • getSupportedTags

      public List<String> getSupportedTags()
    • setSupportedTags

      public void setSupportedTags(List<String> supportedTags)
      Limits the exported tags to a specific set of tags.

      The value must be a list of strings. This property requires that getTags() is set to true in order to have an effect.

      Parameters:
      supportedTags - The set of tags to export.
    • getKeepUnusedComponents

      public boolean getKeepUnusedComponents()
    • setKeepUnusedComponents

      public void setKeepUnusedComponents(boolean keepUnusedComponents)
      Set to true to prevent unused OpenAPI components from being removed from the created specification.
      Parameters:
      keepUnusedComponents - Set to true to keep unused components.
    • getJsonContentType

      public String getJsonContentType()
    • setJsonContentType

      public void setJsonContentType(String jsonContentType)
      Sets a custom media-type to associate with the JSON payload of JSON-based protocols.
      Parameters:
      jsonContentType - Content-Type to use for JSON protocols by default.
    • getForbidGreedyLabels

      public boolean getForbidGreedyLabels()
    • setForbidGreedyLabels

      public void setForbidGreedyLabels(boolean forbidGreedyLabels)
      Set to true to forbid greedy URI labels.

      By default, greedy labels will appear as-is in the path generated for an operation. For example, "/{foo+}".

      Parameters:
      forbidGreedyLabels - Set to true to forbid greedy labels.
    • getRemoveGreedyParameterSuffix

      public boolean getRemoveGreedyParameterSuffix()
    • setRemoveGreedyParameterSuffix

      public void setRemoveGreedyParameterSuffix(boolean removeGreedyParameterSuffix)
      Set to true to remove the "+" suffix that is added to the generated parameter name for greedy labels.

      By default, greedy labels will have a parameter name generated that matches the label, including the "+" suffix.

      Parameters:
      removeGreedyParameterSuffix - Set to true to remove the "+" suffix on generated parameter name.
    • getOnHttpPrefixHeaders

      public OpenApiConfig.HttpPrefixHeadersStrategy getOnHttpPrefixHeaders()
    • setOnHttpPrefixHeaders

      public void setOnHttpPrefixHeaders(OpenApiConfig.HttpPrefixHeadersStrategy onHttpPrefixHeaders)
      Specifies what to do when the httpPrefixHeaders} trait is found in a model.

      OpenAPI does not support httpPrefixHeaders. By default, the conversion will fail when this trait is encountered, but this behavior can be customized. By default, the conversion fails when prefix headers are encountered.

      Parameters:
      onHttpPrefixHeaders - Strategy to use for prefix headers.
    • getIgnoreUnsupportedTraits

      public boolean getIgnoreUnsupportedTraits()
    • setIgnoreUnsupportedTraits

      public void setIgnoreUnsupportedTraits(boolean ignoreUnsupportedTraits)
      Set to true to emit warnings rather than failing when unsupported traits like endpoint and hostLabel are encountered.
      Parameters:
      ignoreUnsupportedTraits - True to ignore unsupported traits.
    • getSubstitutions

      public Map<String,Node> getSubstitutions()
    • setSubstitutions

      public void setSubstitutions(Map<String,Node> substitutions)
      Defines a map of strings to any JSON value to find and replace in the generated OpenAPI model.

      String values are replaced if the string in its entirety matches one of the keys provided in the substitutions map. The corresponding value is then substituted for the string; this could even result in a string changing into an object, array, etc.

      Parameters:
      substitutions - Map of substitutions.
    • getJsonAdd

      public Map<String,Node> getJsonAdd()
    • setJsonAdd

      public void setJsonAdd(Map<String,Node> jsonAdd)
      Adds or replaces the JSON value in the generated OpenAPI document at the given JSON pointer locations with a different JSON value.

      The value must be a map where each key is a valid JSON pointer string as defined in RFC 6901. Each value in the map is the JSON value to add or replace at the given target.

      Values are added using similar semantics of the "add" operation of JSON Patch, as specified in RFC 6902, with the exception that adding properties to an undefined object will create nested objects in the result as needed.

      Parameters:
      jsonAdd - Map of JSON path to values to patch in.
    • getExternalDocs

      public List<String> getExternalDocs()
    • setExternalDocs

      public void setExternalDocs(List<String> externalDocs)
      Limits the source of converted "externalDocs" fields to the specified priority ordered list of names in an externalDocumentation trait.

      This list is case insensitive. By default, this is a list of the following values: "Homepage", "API Reference", "User Guide", "Developer Guide", "Reference", and "Guide".

      Parameters:
      externalDocs - External docs to look for and convert, in order.
    • getVersion

      public OpenApiVersion getVersion()
    • setVersion

      public void setVersion(OpenApiVersion version)
    • getDisableIntegerFormat

      public boolean getDisableIntegerFormat()
    • setDisableIntegerFormat

      public void setDisableIntegerFormat(boolean disableIntegerFormat)
      Set to true to disable setting the `format` property on integer types.
      Parameters:
      disableIntegerFormat - True to disable setting format on integer types.
    • getOnErrorStatusConflict

      public OpenApiConfig.ErrorStatusConflictHandlingStrategy getOnErrorStatusConflict()
    • setOnErrorStatusConflict

      public void setOnErrorStatusConflict(OpenApiConfig.ErrorStatusConflictHandlingStrategy onErrorStatusConflict)
      Specifies what to do when multiple error responses share the same HTTP status code.
      Parameters:
      onErrorStatusConflict - Strategy to use for multiple errors with same status code.
    • fromNode

      public static OpenApiConfig fromNode(Node input)
      Creates an OpenApiConfig from a Node value.

      This method first converts deprecated keys into their new locations and formats, and then uses the NodeMapper on the converted input object. Note that this class can be deserialized using a NodeMapper too since the NodeMapper will look for a static, public, fromNode method.

      This method also serializes unknown properties into the "extensions" map so that they are accessible to OpenAPI mappers.

      Parameters:
      input - Input to deserialize.
      Returns:
      Returns the deserialized OpenApiConfig.
    • setJsonSchemaVersion

      public void setJsonSchemaVersion(JsonSchemaVersion schemaVersion)
      Description copied from class: JsonSchemaConfig
      Set the JSON schema version to use when converting Smithy shapes into Json Schema.
      Overrides:
      setJsonSchemaVersion in class JsonSchemaConfig
      Parameters:
      schemaVersion - JSON Schema version to use for generated schema