Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make protocol and auth traits #273

Merged
merged 20 commits into from
Feb 8, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update openapi converters to use typed traits
OpenAPI conversion now uses the protocol auth traits. Further, Context
and security scheme converters are now generic over the protocol/auth
trait they convert, making them easier to implement.
  • Loading branch information
mtdowling committed Feb 5, 2020
commit 175ef6dba6993bed0a25f2b1ea5bbdb4f8d1d639
18 changes: 11 additions & 7 deletions docs/source/guides/converting-to-openapi.rst
Original file line number Diff line number Diff line change
@@ -114,7 +114,7 @@ The Smithy Gradle plugin relies on a ``smithy-build.json`` file found at the
root of a project to define the actual process of building the OpenAPI
specification. The following example defines a ``smithy-build.json`` file
that builds an OpenAPI specification from a service for the
``smithy.example#Weather`` service using the ``aws.rest-json-1.1`` protocol:
``smithy.example#Weather`` service using the ``aws.protocols#restJson1`` protocol:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We decided to use restJson1 rather than just restJson since we eventually plan to ship an improved REST+JSON protocol.


.. code-block:: json
:caption: smithy-build.json
@@ -125,7 +125,7 @@ that builds an OpenAPI specification from a service for the
"plugins": {
"openapi": {
"service": "smithy.example#Weather",
"protocol": "aws.rest-json-1.1"
"protocol": "aws.protocols#restJson1"
}
}
}
@@ -155,14 +155,18 @@ service (string)
**Required**. The Smithy service :ref:`shape ID <shape-id>` to convert.

protocol (string)
The protocol name to use when converting Smithy to OpenAPI (for example,
``aws.rest-json-1.1``.
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 ``software.amazon.smithy.openapi.fromsmithy.OpenApiProtocol``
registered with a service provider implementation of
``software.amazon.smithy.openapi.fromsmithy.CoreExtension``.

.. important::

This property is required if a service supports multiple protocols.

openapi.tags (boolean)
Whether or not to include Smithy :ref:`tags <tags-trait>` in the result.

@@ -197,8 +201,8 @@ openapi.keepUnusedComponents (boolean)
created specification.

openapi.aws.jsonContentType (string)
Sets the media-type to associate with the JSON payload of ``aws.json-*``
and ``aws.rest-json-*`` protocols
Sets a custom media-type to associate with the JSON payload of
JSON-based protocols.

openapi.forbidGreedyLabels (boolean)
Set to true to forbid greedy URI labels. By default, greedy labels will
@@ -532,7 +536,7 @@ Next, you need to create and configure an ``OpenApiConverter``:
OpenApiConverter converter = OpenApiConverter.create();

// Add any necessary settings...
converter.putSetting(OpenApiConstants.PROTOCOL, "aws.rest-json-1.1");
converter.putSetting(OpenApiConstants.PROTOCOL, "aws.protocols#restJson1");

// Create a shape ID that points to the service.
ShapeId serviceShapeId = ShapeId.from("smithy.example#Weather");
1 change: 1 addition & 0 deletions smithy-openapi/build.gradle.kts
Original file line number Diff line number Diff line change
@@ -21,4 +21,5 @@ dependencies {
api(project(":smithy-model"))
api(project(":smithy-build"))
api(project(":smithy-jsonschema"))
api(project(":smithy-aws-traits"))
}
Original file line number Diff line number Diff line change
@@ -27,7 +27,7 @@ public final class OpenApiConstants {
/** The Smithy service Shape ID to convert. */
public static final String SERVICE = "service";

/** The protocol name to use when converting Smithy to OpenAPI. */
/** The protocol trait shape ID to use when converting Smithy to OpenAPI. */
public static final String PROTOCOL = "protocol";

/** Whether or not to include tags in the result. */
Original file line number Diff line number Diff line change
@@ -23,34 +23,33 @@
import software.amazon.smithy.model.node.ObjectNode;
import software.amazon.smithy.model.shapes.ServiceShape;
import software.amazon.smithy.model.shapes.ToShapeId;
import software.amazon.smithy.model.traits.Protocol;
import software.amazon.smithy.model.traits.Trait;
import software.amazon.smithy.openapi.OpenApiException;

/**
* Smithy to OpenAPI conversion context object.
*/
public final class Context {
public final class Context<T extends Trait> {
private final Model model;
private final ServiceShape service;
private final JsonSchemaConverter jsonSchemaConverter;
private final Protocol protocol;
private final OpenApiProtocol openApiProtocol;
private final T protocolTrait;
private final OpenApiProtocol<T> openApiProtocol;
private final SchemaDocument schemas;
private final List<SecuritySchemeConverter> securitySchemeConverters;
private final List<SecuritySchemeConverter<? extends Trait>> securitySchemeConverters;

public Context(
Model model,
ServiceShape service,
JsonSchemaConverter jsonSchemaConverter,
Protocol protocol,
OpenApiProtocol openApiProtocol,
OpenApiProtocol<T> openApiProtocol,
SchemaDocument schemas,
List<SecuritySchemeConverter> securitySchemeConverters
List<SecuritySchemeConverter<? extends Trait>> securitySchemeConverters
) {
this.model = model;
this.service = service;
this.jsonSchemaConverter = jsonSchemaConverter;
this.protocol = protocol;
this.protocolTrait = service.expectTrait(openApiProtocol.getProtocolType());
this.openApiProtocol = openApiProtocol;
this.schemas = schemas;
this.securitySchemeConverters = securitySchemeConverters;
@@ -95,29 +94,20 @@ public JsonSchemaConverter getJsonSchemaConverter() {
}

/**
* Gets the name of the protocol that is used in the conversion.
* Gets the protocol trait that is being converted.
*
* @return Returns the protocol name.
* @return Returns the protocol ID.
*/
public String getProtocolName() {
return protocol.getName();
}

/**
* Gets the protocols trait protocol being used for the conversion.
*
* @return Returns the protocol being used.
*/
public Protocol getProtocol() {
return protocol;
public T getProtocolTrait() {
return protocolTrait;
}

/**
* Gets the OpenAPI protocol conversion object.
*
* @return Returns the OpenAPI protocol.
*/
public OpenApiProtocol getOpenApiProtocol() {
public OpenApiProtocol<T> getOpenApiProtocol() {
return openApiProtocol;
}

@@ -160,7 +150,7 @@ public Schema createRef(ToShapeId shapeId) {
*
* @return Returns the security scheme converters.
*/
public List<SecuritySchemeConverter> getSecuritySchemeConverters() {
public List<SecuritySchemeConverter<? extends Trait>> getSecuritySchemeConverters() {
return securitySchemeConverters;
}

Original file line number Diff line number Diff line change
@@ -17,6 +17,7 @@

import java.util.List;
import software.amazon.smithy.jsonschema.JsonSchemaMapper;
import software.amazon.smithy.model.traits.Trait;
import software.amazon.smithy.openapi.fromsmithy.mappers.CheckForGreedyLabels;
import software.amazon.smithy.openapi.fromsmithy.mappers.CheckForPrefixHeaders;
import software.amazon.smithy.openapi.fromsmithy.mappers.InlineReferencesToPrimitiveTypes;
@@ -37,18 +38,18 @@
*/
public final class CoreExtension implements Smithy2OpenApiExtension {
@Override
public List<SecuritySchemeConverter> getSecuritySchemeConverters() {
public List<SecuritySchemeConverter<? extends Trait>> getSecuritySchemeConverters() {
return ListUtils.of(
new AwsV4(),
new HttpBasic(),
new HttpBearer(),
new HttpDigest(),
new AwsV4(),
new XApiKey()
);
}

@Override
public List<OpenApiProtocol> getProtocols() {
public List<OpenApiProtocol<? extends Trait>> getProtocols() {
return ListUtils.of(new AwsRestJsonProtocol());
}

Loading