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.

Sign up for GitHub

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

Correct documentation for @length and @auth traits #988

Merged
merged 6 commits into from
Nov 23, 2021
Merged

Correct documentation for @length and @auth traits #988

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1cd67f1
Corrected trait selector documentation for @length constraint
Nov 18, 2021
5602ed8
Corrected and expanded documentation for @auth trait
Nov 18, 2021
46bdbac
Spelling correction
crossleydominic Nov 22, 2021
b8c4656
Spelling correction
crossleydominic Nov 22, 2021
6320c72
Spelling corrections
crossleydominic Nov 22, 2021
753dca5
Spelling and grammatical corrections
crossleydominic Nov 22, 2021
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
146 changes: 109 additions & 37 deletions docs/source/1.0/spec/core/auth-traits.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,76 +305,148 @@ Value type
shape.

Operations that are not annotated with the ``auth`` trait inherit the ``auth``
trait of the service they are bound to, and if the operation is not annotated
with the ``auth`` trait, then the operation is expected to support each of
the :ref:`authentication scheme traits <authDefinition-trait>` applied to the
trait of the service they are bound to. If the operation is not annotated with
the ``auth`` trait, and the service it is bound to is also not annotated with
the ``auth`` trait, then the operation is expected to support each of the
:ref:`authentication scheme traits <authDefinition-trait>` applied to the
service. Each entry in the ``auth`` trait is a shape ID that MUST refer to an
authentication scheme trait applied to the service in which it is bound.

The following example defines two operations:
The following example defines all combinations in which ``auth`` can be applied
to services and operations:

* OperationA defines an explicit list of the authentication schemes it
supports using the ``auth`` trait.
* OperationB is not annotated with the ``auth`` trait, so the schemes
supported by this operation inherit all of the authentication schemes
applied to the service.
* ``ServiceWithNoAuthTrait`` does not use the ``auth`` trait and binds two
operations:

* ``OperationA`` is not annoated with the ``auth`` trait and inherits all
crossleydominic marked this conversation as resolved.
Show resolved Hide resolved
of the authentication scheme applied to the service.

* ``OperationB`` is annoated with the ``auth`` defines an explicit list of
crossleydominic marked this conversation as resolved.
Show resolved Hide resolved
authentication schemes.

* ``ServiceWithAuthTrait`` is annotated with the ``auth`` trait and binds two
operations:

* ``OperationC`` is not annoated with the ``auth`` trait and inherits all
crossleydominic marked this conversation as resolved.
Show resolved Hide resolved
of the authentication schemes applied via the ``auth`` trait on the
service.

* ``OperationD`` is annoated with the ``auth`` defines an explicit list of
crossleydominic marked this conversation as resolved.
Show resolved Hide resolved
authentication schemes.

.. tabs::

.. code-tab:: smithy

@httpBasicAuth
@httpDigestAuth
@auth([httpBasicAuth])
service AuthenticatedService {
version: "2017-02-11",
operations: [OperationA, OperationB]
@httpBearerAuth
service ServiceWithNoAuthTrait {
version: "2020-01-29",
operations: [
OperationA,
OperationB
]
}

// This operation is configured to only support httpDigestAuth.
// It is not expected to support httpBasicAuth.
@auth([httpDigestAuth])
// This operation does not have the @auth trait and is bound to a service
// without the @auth trait. The effective set of authentication schemes it
// supports are: httpBasicAuth, httpDigestAuth and httpBearerAuth
operation OperationA {}

// This operation defines no auth trait, so it is expected to
// support the effective authentication schemes of the service:
// httpBasicAuth and httpDigestAuth.
// This operation does have the @auth trait and is bound to a service
// without the @auth trait. The effective set of authentication schemes it
// supports are: httpDigestAuth.
@auth([httpDigestAuth])
operation OperationB {}

@httpBasicAuth
@httpDigestAuth
@httpBearerAuth
@auth([httpBasicAuth, httpDigestAuth])
service ServiceWithAuthTrait {
version: "2020-01-29",
operations: [
OperationC,
OperationD
]
}

// This operation does not have the @auth trait and is bound to a service
// with the @auth trait. The effective set of authentication schemes it
// supports are: httpBasicAuth, httpDigestAuth
operation OperationC {}

// This operation not have the @auth trait and is bound to a service
crossleydominic marked this conversation as resolved.
Show resolved Hide resolved
// with the @auth trait. The effective set of authentication schemes it
// supports are: httpBearerAuth
@auth([httpBearerAuth])
operation OperationD {}

.. code-tab:: json

{
"smithy": "1.0",
"shapes": {
"smithy.example#AuthenticatedService": {
"type": "service",
"version": "2017-02-11",
"operations": [
{
"target": "smithy.example#OperationA"
},
{
"target": "smithy.example#OperationB"
}
],
"smithy.example#OperationA": {
"type": "operation"
},
"smithy.example#OperationB": {
"type": "operation",
"traits": {
"smithy.api#httpBasicAuth": {},
"smithy.api#httpDigestAuth": {},
"smithy.api#auth": [
"smithy.api#httpBasicAuth"
"smithy.api#httpDigestAuth"
]
}
},
"smithy.example#OperationA": {
"smithy.example#OperationC": {
"type": "operation"
},
"smithy.example#OperationD": {
"type": "operation",
"traits": {
"smithy.api#auth": [
"smithy.api#httpDigestAuth"
"smithy.api#httpBearerAuth"
]
}
},
"smithy.example#OperationB": {
"type": "operation"
"smithy.example#ServiceWithAuthTrait": {
"type": "service",
"traits": {
"smithy.api#auth": [
"smithy.api#httpBasicAuth",
"smithy.api#httpDigestAuth"
],
"smithy.api#httpBasicAuth": {},
"smithy.api#httpBearerAuth": {},
"smithy.api#httpDigestAuth": {}
},
"version": "2020-01-29",
"operations": [
{
"target": "smithy.example#OperationC"
},
{
"target": "smithy.example#OperationD"
}
]
},
"smithy.example#ServiceWithNoAuthTrait": {
"type": "service",
"traits": {
"smithy.api#httpBasicAuth": {},
"smithy.api#httpBearerAuth": {},
"smithy.api#httpDigestAuth": {}
},
"version": "2020-01-29",
"operations": [
{
"target": "smithy.example#OperationA"
},
{
"target": "smithy.example#OperationB"
}
]
}
}
}
Expand Down
2 changes: 1 addition & 1 deletion docs/source/1.0/spec/core/constraint-traits.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,7 @@ Given the following model,
Summary
Constrains a shape to minimum and maximum number of elements or size.
Trait selector
``:test(list, map, string, blob, member > :is(list, map, string, blob))``
``:test(collection, map, string, blob, member > :is(collection, map, string, blob))``

*Any list, map, string, or blob; or a member that targets one of these shapes*
Value type
Expand Down