software.amazon.smithy.openapi

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OpenApiConfig.HttpPrefixHeadersStrategy Specifies what to do when the httpPrefixHeaders trait is found in a model.

Nested classes/interfaces inherited from class software.amazon.smithy.jsonschema.JsonSchemaConfig

JsonSchemaConfig.MapStrategy, JsonSchemaConfig.UnionStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VERSION The supported version of OpenAPI.

Constructor Summary

Constructors

Constructor and Description
OpenApiConfig()

Method Summary

Modifier and Type	Method and Description
static OpenApiConfig	fromNode(Node input) Creates an OpenApiConfig from a Node value.
java.lang.String	getDefaultBlobFormat()
java.util.List<java.lang.String>	getExternalDocs()
boolean	getForbidGreedyLabels()
boolean	getIgnoreUnsupportedTraits()
java.util.Map<java.lang.String,Node>	getJsonAdd()
java.lang.String	getJsonContentType()
boolean	getKeepUnusedComponents()
OpenApiConfig.HttpPrefixHeadersStrategy	getOnHttpPrefixHeaders()
ShapeId	getProtocol()
boolean	getRemoveGreedyParameterSuffix()
java.util.Map<java.lang.String,Node>	getSubstitutions()
java.util.List<java.lang.String>	getSupportedTags()
boolean	getTags()
boolean	getUseIntegerType()
void	setDefaultBlobFormat(java.lang.String defaultBlobFormat) Sets the default OpenAPI format property used when converting blob shapes in Smithy to strings in OpenAPI.
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.
void	setForbidGreedyLabels(boolean forbidGreedyLabels) Set to true to forbid greedy URI labels.
void	setIgnoreUnsupportedTraits(boolean ignoreUnsupportedTraits) Set to true to emit warnings rather than failing when unsupported traits like endpoint and hostLabel are encountered.
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.
void	setJsonContentType(java.lang.String jsonContentType) Sets a custom media-type to associate with the JSON payload of JSON-based protocols.
void	setKeepUnusedComponents(boolean keepUnusedComponents) Set to true to prevent unused OpenAPI components from being removed from the created specification.
void	setOnHttpPrefixHeaders(OpenApiConfig.HttpPrefixHeadersStrategy onHttpPrefixHeaders) Specifies what to do when the httpPrefixHeaders} trait is found in a model.
void	setProtocol(ShapeId protocol) Sets the protocol shape ID to use when converting Smithy to OpenAPI.
void	setRemoveGreedyParameterSuffix(boolean removeGreedyParameterSuffix) Set to true to remove the "+" suffix that is added to the generated parameter name for greedy labels.
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.
void	setSupportedTags(java.util.List<java.lang.String> supportedTags) Limits the exported tags to a specific set of tags.
void	setTags(boolean tags) Sets whether or not to include Smithy tags in the result as OpenAPI tags.
void	setUseIntegerType(boolean useIntegerType) Set to true to use the "integer" type when converting byte, short, integer, and long shapes to OpenAPI.

Methods inherited from class software.amazon.smithy.jsonschema.JsonSchemaConfig

detectJsonTimestampFormat, getAlphanumericOnlyRefs, getDefaultTimestampFormat, getDefinitionPointer, getDisableFeatures, getExtensions, getExtensions, getMapStrategy, getSchemaDocumentExtensions, getService, getSupportNonNumericFloats, getUnionStrategy, getUseJsonName, isEnableOutOfServiceReferences, putExtension, putExtension, putExtension, putExtensions, setAlphanumericOnlyRefs, setDefaultTimestampFormat, setDefinitionPointer, setDisableFeatures, setEnableOutOfServiceReferences, setExtensions, setMapStrategy, setSchemaDocumentExtensions, setService, setSupportNonNumericFloats, setUnionStrategy, setUseJsonName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION

public static final java.lang.String VERSION

The supported version of OpenAPI.

See Also:

Constant Field Values

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.

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

getUseIntegerType

public boolean getUseIntegerType()

setUseIntegerType

public void setUseIntegerType(boolean useIntegerType)

Set to true to use the "integer" type when converting byte, short, integer, and long shapes to OpenAPI.

By default, these shape types are converted to OpenAPI with a type of "number".

Parameters:

useIntegerType - True to use "integer".

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.