From 83aff45c881d5b5e9e705e7ec3fc34d50d2b54a1 Mon Sep 17 00:00:00 2001 From: Jan Sepke <625043+jansepke@users.noreply.github.com> Date: Fri, 9 Apr 2021 18:57:41 +0200 Subject: [PATCH] docs(appsync): fix heading levels (#14073) The current heading levels for the [AppSync Docs](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-appsync-readme.html) seem not aligned. This PR tries to introduce better nesting: * group examples under example heading * move headings under Aurora Serverless one level up * group types under GraphQL Types ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- packages/@aws-cdk/aws-appsync/README.md | 48 ++++++++++++------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/packages/@aws-cdk/aws-appsync/README.md b/packages/@aws-cdk/aws-appsync/README.md index d15051d191a25..e0a636217f38b 100644 --- a/packages/@aws-cdk/aws-appsync/README.md +++ b/packages/@aws-cdk/aws-appsync/README.md @@ -26,7 +26,7 @@ APIs that use GraphQL. ## Example -## DynamoDB +### DynamoDB Example of a GraphQL API with `AWS_IAM` authorization resolving into a DynamoDb backend data source. @@ -95,7 +95,7 @@ demoDS.createResolver({ }); ``` -## Aurora Serverless +### Aurora Serverless AppSync provides a data source for executing SQL commands against Amazon Aurora Serverless clusters. You can use AppSync resolvers to execute SQL statements @@ -240,13 +240,13 @@ httpDs.createResolver({ }); ``` -### Schema +## Schema Every GraphQL Api needs a schema to define the Api. CDK offers `appsync.Schema` for static convenience methods for various types of schema declaration: code-first or schema-first. -#### Code-First +### Code-First When declaring your GraphQL Api, CDK defaults to a code-first approach if the `schema` property is not configured. @@ -274,7 +274,7 @@ const api = new appsync.GraphqlApi(stack, 'api', { See the [code-first schema](#Code-First-Schema) section for more details. -#### Schema-First +### Schema-First You can define your GraphQL Schema from a file on disk. For convenience, use the `appsync.Schema.fromAsset` to specify the file representing your schema. @@ -286,7 +286,7 @@ const api = appsync.GraphqlApi(stack, 'api', { }); ``` -### Imports +## Imports Any GraphQL Api that has been created outside the stack can be imported from another stack into your CDK app. Utilizing the `fromXxx` function, you have @@ -304,7 +304,7 @@ If you don't specify `graphqlArn` in `fromXxxAttributes`, CDK will autogenerate the expected `arn` for the imported api, given the `apiId`. For creating data sources and resolvers, an `apiId` is sufficient. -### Permissions +## Permissions When using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role with correct permissions must be used for access to API. @@ -358,7 +358,7 @@ const api = new appsync.GraphqlApi(stack, 'API', { api.grant(role, appsync.IamResource.custom('types/Mutation/fields/updateExample'), 'appsync:GraphQL') ``` -#### IamResource +### IamResource In order to use the `grant` functions, you need to use the class `IamResource`. @@ -368,7 +368,7 @@ In order to use the `grant` functions, you need to use the class `IamResource`. - `IamResource.all()` permits ALL resources. -#### Generic Permissions +### Generic Permissions Alternatively, you can use more generic `grant` functions to accomplish the same usage. @@ -386,7 +386,7 @@ api.grantMutation(role, 'updateExample'); api.grant(role, appsync.IamResource.ofType('Mutation', 'updateExample'), 'appsync:GraphQL'); ``` -### Pipeline Resolvers and AppSync Functions +## Pipeline Resolvers and AppSync Functions AppSync Functions are local functions that perform certain operations onto a backend data source. Developers can compose operations (Functions) and execute @@ -418,7 +418,7 @@ const pipelineResolver = new appsync.Resolver(stack, 'pipeline', { Learn more about Pipeline Resolvers and AppSync Functions [here](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html). -### Code-First Schema +## Code-First Schema CDK offers the ability to generate your schema in a code-first approach. A code-first approach offers a developer workflow with: @@ -429,7 +429,7 @@ A code-first approach offers a developer workflow with: The code-first approach allows for **dynamic** schema generation. You can generate your schema based on variables and templates to reduce code duplication. -#### Code-First Example +### Code-First Example To showcase the code-first approach. Let's try to model the following schema segment. @@ -545,7 +545,7 @@ create the base Object Type (i.e. Film) and from there we can generate its respe Check out a more in-depth example [here](https://github.com/BryanPan342/starwars-code-first). -#### GraphQL Types +## GraphQL Types One of the benefits of GraphQL is its strongly typed nature. We define the types within an object, query, mutation, interface, etc. as **GraphQL Types**. @@ -562,7 +562,7 @@ More concretely, GraphQL Types are simply the types appended to variables. Referencing the object type `Demo` in the previous example, the GraphQL Types is `String!` and is applied to both the names `id` and `version`. -#### Directives +### Directives `Directives` are attached to a field or type and affect the execution of queries, mutations, and types. With AppSync, we use `Directives` to configure authorization. @@ -577,12 +577,12 @@ through `Cognito User Pools` To learn more about authorization and directives, read these docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/security.html). -#### Field and Resolvable Fields +### Field and Resolvable Fields While `GraphqlType` is a base implementation for GraphQL fields, we have abstractions on top of `GraphqlType` that provide finer grain support. -#### Field +### Field `Field` extends `GraphqlType` and will allow you to define arguments. [**Interface Types**](#Interface-Types) are not resolvable and this class will allow you to define arguments, but not its resolvers. @@ -609,7 +609,7 @@ const type = new appsync.InterfaceType('Node', { }); ``` -#### Resolvable Fields +### Resolvable Fields `ResolvableField` extends `Field` and will allow you to define arguments and its resolvers. [**Object Types**](#Object-Types) can have fields that resolve and perform operations on @@ -671,7 +671,7 @@ const query = new appsync.ObjectType('Query', { Learn more about fields and resolvers [here](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html). -#### Intermediate Types +### Intermediate Types Intermediate Types are defined by Graphql Types and Fields. They have a set of defined fields, where each field corresponds to another type in the system. Intermediate @@ -703,7 +703,7 @@ const node = new appsync.InterfaceType('Node', { To learn more about **Interface Types**, read the docs [here](https://graphql.org/learn/schema/#interfaces). -##### Object Types +#### Object Types **Object Types** are types that you declare. For example, in the [code-first example](#code-first-example) the `demo` variable is an **Object Type**. **Object Types** are defined by @@ -775,7 +775,7 @@ You can create Object Types in three ways: To learn more about **Object Types**, read the docs [here](https://graphql.org/learn/schema/#object-types-and-fields). -### Enum Types +#### Enum Types **Enum Types** are a special type of Intermediate Type. They restrict a particular set of allowed values for other Intermediate Types. @@ -832,7 +832,7 @@ api.addType(review); To learn more about **Input Types**, read the docs [here](https://graphql.org/learn/schema/#input-types). -### Union Types +#### Union Types **Union Types** are a special type of Intermediate Type. They are similar to Interface Types, but they cannot specify any common fields between types. @@ -860,7 +860,7 @@ api.addType(search); To learn more about **Union Types**, read the docs [here](https://graphql.org/learn/schema/#union-types). -#### Query +### Query Every schema requires a top level Query type. By default, the schema will look for the `Object Type` named `Query`. The top level `Query` is the **only** exposed @@ -883,7 +883,7 @@ api.addQuery('allFilms', new appsync.ResolvableField({ To learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-overview.html). -#### Mutation +### Mutation Every schema **can** have a top level Mutation type. By default, the schema will look for the `ObjectType` named `Mutation`. The top level `Mutation` Type is the only exposed @@ -906,7 +906,7 @@ api.addMutation('addFilm', new appsync.ResolvableField({ To learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-overview.html). -#### Subscription +### Subscription Every schema **can** have a top level Subscription type. The top level `Subscription` Type is the only exposed type that users can access to invoke a response to a mutation. `Subscriptions`