From 78afd1a57f05220f9a68bce9c8db3b231d92d859 Mon Sep 17 00:00:00 2001 From: Thomas Farr Date: Tue, 7 Mar 2023 10:17:24 +1300 Subject: [PATCH] Documentation fixes --- .../guides/converting-to-openapi.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source-2.0/guides/converting-to-openapi.rst b/docs/source-2.0/guides/converting-to-openapi.rst index 9c74bcd33df..9ce8cf9ecb1 100644 --- a/docs/source-2.0/guides/converting-to-openapi.rst +++ b/docs/source-2.0/guides/converting-to-openapi.rst @@ -941,10 +941,10 @@ The following is an example OpenAPI model for the above Smithy example value. OpenAPI conversion traits ------------------------- -The ``software.amazon.smithy:smithy-openapi-traits`` package defines traits that can be used to augment the conversion +The ``software.amazon.smithy:smithy-openapi-traits`` package defines traits used to augment the conversion of a Smithy model into an OpenAPI specification. -The following example shows how to add it to your Gradle build alongside the ``smithy-openapi`` plugin and ``smithy-build``: +The following example shows how to add it to your Gradle build alongside the ``smithy-openapi`` plugin: .. code-block:: kotlin :caption: build.gradle.kts @@ -975,7 +975,7 @@ Refer to `Converting to OpenAPI with smithy-build`_ for more detailed informatio Summary Indicates a trait shape should be converted into an `OpenAPI specification extension`_. - Any custom trait that has been annotated with this trait, will be serialized into the OpenAPI specification using + Any custom trait that has been annotated with this trait will be serialized into the OpenAPI specification using its :ref:`Smithy JSON AST representation `. Trait selector ``[trait|trait]`` @@ -994,9 +994,10 @@ The ``specificationExtension`` trait is a structure that supports the following * - as - ``string`` - Explicitly name the specification extension. - If set must begin with ``"x-"``, otherwise defaults to the target trait shape's ID normalized with hyphens and prepended with ``"x-"``. + If set, it must begin with ``"x-"``. + Otherwise, it defaults to the target trait's shape ID normalized with hyphens and prepended with ``"x-"``. -The following example defines a custom structure trait representing custom metadata, using the ``specificationExtension`` trait: +The following example defines a specification extension representing a custom metadata structure using the ``specificationExtension`` trait: .. code-block:: smithy @@ -1024,7 +1025,7 @@ The following example defines a custom structure trait representing custom metad output: GreetResponse } -This results in an ``x-meta`` property being added to the respective objects in the OpenAPI output, like below: +This results in an ``x-meta`` property being added to the respective objects in the OpenAPI output: .. code-block:: json @@ -1071,8 +1072,7 @@ This results in an ``x-meta`` property being added to the respective objects in .. rubric:: Supported trait locations: -Currently only a limited subset of trait target locations are supported in the conversion, -all other locations including on members of the below shapes are ignored: +Only a subset of OpenAPI locations are supported in the conversion: .. list-table:: :header-rows: 1 @@ -1087,7 +1087,7 @@ all other locations including on members of the below shapes are ignored: * - Simple & Aggregate shapes - `Schema object `_ -Most other unsupported use cases can likely be covered by the :ref:`jsonAdd ` feature of the ``smithy-openapi`` plugin. +Unsupported use cases can likely be covered by the :ref:`jsonAdd ` feature of the ``smithy-openapi`` plugin. ----------------------------- Amazon API Gateway extensions