Package software.amazon.smithy.openapi

Class OpenApiConfig

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

    • Constructor Detail

      • OpenApiConfig

        public OpenApiConfig()

    • Method Detail

      • 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 java.lang.String getDefaultBlobFormat()

      • setDefaultBlobFormat

        public void setDefaultBlobFormat​(java.lang.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 java.util.List<java.lang.String> getSupportedTags()

      • setSupportedTags

        public void setSupportedTags​(java.util.List<java.lang.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 java.lang.String getJsonContentType()

      • setJsonContentType

        public void setJsonContentType​(java.lang.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.

      • 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 java.util.Map<java.lang.String,​Node> getSubstitutions()

      • setSubstitutions

        public void setSubstitutions​(java.util.Map<java.lang.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 java.util.Map<java.lang.String,​Node> getJsonAdd()

      • setJsonAdd

        public void setJsonAdd​(java.util.Map<java.lang.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 java.util.List<java.lang.String> getExternalDocs()

      • setExternalDocs

        public void setExternalDocs​(java.util.List<java.lang.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.

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

      • 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