Converting Smithy to OpenAPI¶

Unsupported features¶

Converting a Smithy model to OpenAPI results in a trimmed-down, lossy representation of a model for a specific HTTP protocol. Various features in a Smithy model are not currently supported in the OpenAPI conversion:

• HTTP prefix headers: "Prefix headers" are used in Smithy to bind all headers under a common prefix into a single property of the input or output of an API operation. This can be used for things like Amazon S3's x-amz-meta-* headers. OpenAPI does not currently support this kind of header.
• Greedy labels: Greedy labels are used in HTTP URIs to act as a placeholder for multiple segments of a URI (for example, /foo/{baz+}/bar). Some OpenAPI vendors/tooling support greedy labels (for example, Amazon API Gateway) while other do not. The converter will pass greedy labels through into the OpenAPI document by default, but they can be forbidden through the openapi.forbidGreedyLabels flag.
• Event streams: Event streams are a way of sending many different messages over a stream. This is not currently implemented in the converter (see #80).
• Streaming: Smithy allows blob and string shapes to be marked as streaming, meaning that their contents should not be loaded into memory by clients or servers. This is not currently something supported as a built-in feature of OpenAPI (we could potentially add an extension to mark a specific type as streaming).
• Custom traits: Custom traits defined in a Smithy model are not converted and added to the OpenAPI specification. Copying Smithy traits into OpenAPI as extensions requires the use of a custom software.amazon.smithy.openapi.fromsmithy.OpenApiExtension.
• Non-RESTful routing: HTTP routing schemes that aren't based on methods and unique URIs are not supported in OpenAPI (for example, routing to operations based on a specific header or query string parameter).
• Non-HTTP protocols: Protocols that do not send requests over HTTP are not supported with OpenAPI (for example, an MQTT-based protocol modeled with Smithy would need to also support an HTTP-based protocol to be converted to OpenAPI).
• Resources: Smithy resource metadata is not carried over into the OpenAPI specification.

OpenAPI configuration settings¶

The openapi plugin is highly configurable to support different OpenAPI tools and vendors.

The following key-value pairs are supported:

service (string)

Required. The Smithy service shape ID to convert.

protocol (string)

The protocol name to use when converting Smithy to OpenAPI (for example, aws.rest-json-1.1.

Smithy will try to match the provided protocol name with an implementation of software.amazon.smithy.openapi.fromsmithy.OpenApiProtocol registered with a service provider implementation of software.amazon.smithy.openapi.fromsmithy.CoreExtension.

openapi.tags (boolean)

Whether or not to include Smithy tags in the result.

openapi.supportedTags ([string])

Limits the exported openapi.tags to a specific set of tags. The value must be a list of strings. This property requires that openapi.tags is set to true in order to have an effect.

{
    "version": "1.0",
    "plugins": {
        "openapi": {
            "service": "smithy.example#Weather",
            "openapi.tags": true,
            "openapi.supportedTags": ["foo", "baz", "bar"]
        }
    }
}

openapi.defaultBlobFormat (string)

Sets the default format property used when converting blob shapes in Smithy to strings in OpenAPI. Defaults to "byte", meaning Base64 encoded.

openapi.use.xml (boolean)

Enables converting Smithy XML traits to OpenAPI XML properties. (this feature is not yet implemented).

openapi.keepUnusedComponents (boolean)

Set to true to prevent unused components from being removed from the created specification.

openapi.aws.jsonContentType (string)

Sets the media-type to associate with the JSON payload of aws.json-* and aws.rest-json-* protocols

openapi.forbidGreedyLabels (boolean)

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+}".

openapi.onHttpPrefixHeaders (string)

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 using the following values for the openapi.onHttpPrefixHeaders setting:

• FAIL: The default setting that causes the build to fail.
• WARN: The header is omitted from the OpenAPI model and a warning is logged.

Note

Additional values may be supported by other mappers or protocols.

{
    "version": "1.0",
    "plugins": {
        "openapi": {
            "service": "smithy.example#Weather",
            "openapi.onHttpPrefixHeaders": "WARN"
        }
    }
}

openapi.ignoreUnsupportedTrait (boolean)

Emits warnings rather than failing when unsupported traits like eventStream are encountered.

openapi.disablePrimitiveInlining (boolean)

Disables the automatic inlining of primitive $ref targets.

Inlining these primitive references helps to make the generated OpenAPI models more idiomatic while leaving complex types as-is so that they support recursive types.

A primitive reference is considered one of the following OpenAPI types:

• integer
• number
• boolean
• string

A primitive collection is an array that has an "items" property that targets a primitive reference, or an object with no "properties" and an "additionalProperties" reference that targets a primitive type.

openapi.substitutions (Map<String, any>)

Defines a map of strings to any JSON value to find and replace in the generated OpenAPI model.

This allows for placeholders to appear in the value of Smithy traits that can be converted at build-time to an appropriate value.

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

The following example will find all strings with a value of "REPLACE_ME" and replace the string with an array value of ["this is a", " replacement"] and replace all strings with a value of ANOTHER_REPLACEMENT with Hello!!!:

{
    "version": "1.0",
    "plugins": {
        "openapi": {
            "service": "smithy.example#Weather",
            "openapi.substitutions": {
                "REPLACE_ME": ["this is a", " replacement"],
                "ANOTHER_REPLACEMENT": "Hello!!!"
            }
        }
    }
}

JSON schema configuration settings¶

stripNamespaces (boolean)

Strips Smithy namespaces from the converted shape ID that is generated in the definitions map of a JSON Schema document for a shape. This requires that shape names across all namespaces are unique.

includePrivateShapes (boolean)

Includes shapes marked with the private trait.

useJsonName (boolean)

Uses the value of the jsonName trait when creating JSON schema properties for structure and union shapes.

TODO: This is enabled automatically with AWS protocols?

defaultTimestampFormat (string)

Sets the assumed timestampFormat trait value for timestamps with no explicit timestampFormat trait. The provided value is expected to be a string. Defaults to "date-time" if not set. Can be set to "date-time", "epoch-seconds", or "http-date".

unionStrategy (string)

Configures how Smithy union shapes are converted to JSON Schema.

This property must be a string set to one of the following values:

• oneOf: Converts to a schema that uses "oneOf". This is the default setting used if not configured.
• object: Converts to an empty object "{}".
• structure: Converts to an object with properties just like a structure.

schemaDocumentExtensions (Map<String, any>)

Adds custom top-level key-value pairs to the created OpenAPI specification.

Amazon API Gateway extensions¶

Smithy models can be converted to OpenAPI specifications that contain Amazon API Gateway extensions for defining things like integrations. These API Gateway extensions are automatically picked up by Smithy by adding a dependency on software.amazon.smithy:smithy-aws-apigateway-openapi.

buildscript {
    dependencies {
        classpath("software.amazon.smithy:smithy-aws-apigateway-openapi:0.9.7")
    }
}