-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This adds a documentation section to the service's page covering the available auth types and a notice to each operation's page if it has optional auth, fewer auth types, and/or a different auth type.
- Loading branch information
1 parent
9dacbfb
commit 06ef518
Showing
8 changed files
with
304 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
49 changes: 49 additions & 0 deletions
49
.../src/main/java/software/amazon/smithy/docgen/core/interceptors/ApiKeyAuthInterceptor.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
|
|
||
| package software.amazon.smithy.docgen.core.interceptors; | ||
|
|
||
| import software.amazon.smithy.docgen.core.sections.ShapeDetailsSection; | ||
| import software.amazon.smithy.docgen.core.writers.DocWriter; | ||
| import software.amazon.smithy.model.traits.HttpApiKeyAuthTrait; | ||
| import software.amazon.smithy.model.traits.HttpApiKeyAuthTrait.Location; | ||
| import software.amazon.smithy.utils.CodeInterceptor; | ||
| import software.amazon.smithy.utils.Pair; | ||
| import software.amazon.smithy.utils.SmithyInternalApi; | ||
|
|
||
| /** | ||
| * Adds additional context to the description of api key auth based on the customized values. | ||
| */ | ||
| @SmithyInternalApi | ||
| public final class ApiKeyAuthInterceptor implements CodeInterceptor<ShapeDetailsSection, DocWriter> { | ||
| private static final Pair<String, String> AUTH_HEADER_REF = Pair.of( | ||
| "Authorization header", "https://datatracker.ietf.org/doc/html/rfc9110.html#section-11.4" | ||
| ); | ||
|
|
||
| @Override | ||
| public Class<ShapeDetailsSection> sectionType() { | ||
| return ShapeDetailsSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public boolean isIntercepted(ShapeDetailsSection section) { | ||
| return section.shape().getId().equals(HttpApiKeyAuthTrait.ID); | ||
| } | ||
|
|
||
| @Override | ||
| public void write(DocWriter writer, String previousText, ShapeDetailsSection section) { | ||
| var service = section.context().model().expectShape(section.context().settings().service()); | ||
| var trait = service.expectTrait(HttpApiKeyAuthTrait.class); | ||
| writer.putContext("name", trait.getName()); | ||
| writer.putContext("location", trait.getIn().equals(Location.HEADER) ? "header" : "query string"); | ||
| writer.putContext("scheme", trait.getScheme()); | ||
| writer.putContext("authHeader", AUTH_HEADER_REF); | ||
| writer.write(""" | ||
| The API key must be bound to the ${location:L} using the key ${name:`}.${?scheme} \ | ||
| Additionally, the scheme used in the ${authHeader:R} must be ${scheme:`}.${/scheme} | ||
| $L""", previousText); | ||
| } | ||
| } |
99 changes: 99 additions & 0 deletions
99
...c/main/java/software/amazon/smithy/docgen/core/interceptors/OperationAuthInterceptor.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
|
|
||
| package software.amazon.smithy.docgen.core.interceptors; | ||
|
|
||
| import java.util.List; | ||
| import software.amazon.smithy.docgen.core.DocgenUtils; | ||
| import software.amazon.smithy.docgen.core.sections.ShapeDetailsSection; | ||
| import software.amazon.smithy.docgen.core.writers.DocWriter; | ||
| import software.amazon.smithy.docgen.core.writers.DocWriter.AdmonitionType; | ||
| import software.amazon.smithy.model.knowledge.ServiceIndex; | ||
| import software.amazon.smithy.model.knowledge.ServiceIndex.AuthSchemeMode; | ||
| import software.amazon.smithy.model.shapes.ToShapeId; | ||
| import software.amazon.smithy.model.traits.synthetic.NoAuthTrait; | ||
| import software.amazon.smithy.utils.CodeInterceptor; | ||
| import software.amazon.smithy.utils.SmithyInternalApi; | ||
|
|
||
| /** | ||
| * Adds a priority list of supported auth schemes for operations with optional auth or | ||
| * operations which don't support all of a service's auth schemes. | ||
| */ | ||
| @SmithyInternalApi | ||
| public final class OperationAuthInterceptor implements CodeInterceptor<ShapeDetailsSection, DocWriter> { | ||
| @Override | ||
| public Class<ShapeDetailsSection> sectionType() { | ||
| return ShapeDetailsSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public boolean isIntercepted(ShapeDetailsSection section) { | ||
| if (!section.shape().isOperationShape()) { | ||
| return false; | ||
| } | ||
| var index = ServiceIndex.of(section.context().model()); | ||
| var service = section.context().settings().service(); | ||
|
|
||
| // Only add the admonition if the service has auth in the first place. | ||
| var serviceAuth = index.getAuthSchemes(service); | ||
| if (serviceAuth.isEmpty()) { | ||
| return false; | ||
| } | ||
|
|
||
| // Only add the admonition if the operations' effective auth schemes differs | ||
| // from the total list of available auth schemes on the service. | ||
| var operationAuth = index.getEffectiveAuthSchemes(service, section.shape(), AuthSchemeMode.NO_AUTH_AWARE); | ||
| return !operationAuth.keySet().equals(serviceAuth.keySet()); | ||
| } | ||
|
|
||
| @Override | ||
| public void write(DocWriter writer, String previousText, ShapeDetailsSection section) { | ||
| writer.writeWithNoFormatting(previousText); | ||
| writer.openAdmonition(AdmonitionType.IMPORTANT); | ||
|
|
||
| var index = ServiceIndex.of(section.context().model()); | ||
| var service = section.context().settings().service(); | ||
| var operation = section.shape(); | ||
|
|
||
|
|
||
| var serviceAuth = DocgenUtils.getPrioritizedServiceAuth(section.context().model(), service); | ||
| var operationAuth = List.copyOf( | ||
| index.getEffectiveAuthSchemes(service, operation, AuthSchemeMode.MODELED).keySet()); | ||
|
|
||
| if (serviceAuth.equals(operationAuth)) { | ||
| // If the total service auth and effective *modeled* operation auth are the same, | ||
| // that means that the operation just has optional auth since isIntercepted would | ||
| // return false otherwise. It would have been overly confusing to include this | ||
| // case in the big text block below. | ||
| writer.write(""" | ||
| This operation may be optionally called without authentication. | ||
| """); | ||
| writer.closeAdmonition(); | ||
| return; | ||
| } | ||
|
|
||
| var operationSchemes = operationAuth.stream() | ||
| .map(id -> section.context().symbolProvider().toSymbol(section.context().model().expectShape(id))) | ||
| .toList(); | ||
|
|
||
| writer.putContext("optional", supportsNoAuth(index, service, section.shape())); | ||
| writer.putContext("schemes", operationSchemes); | ||
| writer.putContext("multipleSchemes", operationSchemes.size() > 1); | ||
|
|
||
| writer.write(""" | ||
| ${?schemes}This operation ${?optional}may optionally${/optional}${^optional}MUST${/optional} \ | ||
| be called with ${?multipleSchemes}one of the following priority-ordered auth schemes${/multipleSchemes}\ | ||
| ${^multipleSchemes}the following auth scheme${/multipleSchemes}: \ | ||
| ${#schemes}${value:R}${^key.last}, ${/key.last}${/schemes}.${/schemes}\ | ||
| ${^schemes}${?optional}This operation must be called without authentication.${/optional}${/schemes} | ||
| """); | ||
| writer.closeAdmonition(); | ||
| } | ||
|
|
||
| private boolean supportsNoAuth(ServiceIndex index, ToShapeId service, ToShapeId operation) { | ||
| return index.getEffectiveAuthSchemes(service, operation, AuthSchemeMode.NO_AUTH_AWARE) | ||
| .containsKey(NoAuthTrait.ID); | ||
| } | ||
| } |
24 changes: 24 additions & 0 deletions
24
...hy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/sections/AuthSection.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
|
|
||
| package software.amazon.smithy.docgen.core.sections; | ||
|
|
||
| import software.amazon.smithy.docgen.core.DocGenerationContext; | ||
| import software.amazon.smithy.model.shapes.ServiceShape; | ||
| import software.amazon.smithy.utils.CodeSection; | ||
| import software.amazon.smithy.utils.SmithyInternalApi; | ||
|
|
||
| /** | ||
| * Contains the documentation for the auth schemes that the service supports. | ||
| * | ||
| * @param context The context used to generate documentation. | ||
| * @param service The service whose documentation is being generated. | ||
| * | ||
| * @see ShapeSection to override documentation for individual auth schemes. The shape | ||
| * of the trait is passed as the shape. | ||
| */ | ||
| @SmithyInternalApi | ||
| public record AuthSection(DocGenerationContext context, ServiceShape service) implements CodeSection { | ||
| } |
Oops, something went wrong.