TL;DR;
This article covers how developers can take advantage of the serverless-gql-generator plugin for Serverless Framework to automatically generate new Postman Collections or Raw Requests for an AppSync API.
Introduction
A few weeks ago, I announced the release of a new Serverless Framework Plugin that I had been working on called serverless-gql-generator.
The idea for this plugin came from the difficulties faced during one of my projects where it was too time-consuming for developers to keep the sample requests and Postman Collection for every new schema update. This pain point was further intensified when we started to develop multiple interdependent AppSync APIs simultaneously, requiring multiple Postman Collections to be updated and shared across teams.
In this article, we will cover how to integrate the Serverless Framework plugin into your development flow and CICD pipelines.
Main Plugin Features
As of writing this article, the current version 1.2.1 of the plugin has the following features:
Automatic GraphQL Request Generation - The plugin will generate new requests on demand or during deployment, ensuring they are always up to date with the latest schema version.
Automatic URL & API Key Retrieval - The URL and API Key will be automatically populated with the latest AppSync configuration.
Choose between Inline or using variable file input - Developers can configure the plugin to generate requests with Inline input or with a separate file for variable input.
Exports requests to independent Files and Postman Collections - Depending on the use case, developers can configure the plugin to export the generated requests to independent .graphql files, a Postman Collect or both.
Upload the generated files to S3 - As the icing on the cake, this plugin also automates the upload of the generated files to the configured S3 bucket.
Prerequisites
In order to be able to implement this plugin into your workflow you will at least need:
Node JS installation
AWS Account to deploy the API
A project that uses the Serverless Framework to deploy an AppSync API - examples will be shown using this repository
Postman, GraphBolt or any other tool to send requests and test the generated requests
Installation Process
Installing and adding the plugin to your project is fairly straightforward to accomplish by following two simple steps.
Install the plugin using NPM
Use the following command to install the plugin and save it as a devDependency in your project:
npm install -D serverless-gql-generator
Add the Plugin to your project
Add the plugin under the plugins list in your serverless.yml file
service: my-app
plugins:
- serverless-gql-generator
Using the plugin
After adding the plugin to the plugins list, it will start generating the Postman Collections every time the service is deployed.
The experience can be improved further by configuring the plugin to match your needs better and by using the CLI commands to enable the request generation without the need to redeploy your service.
Overriding the default behaviour
The plugin's default behaviour is to generate (and save locally under the ./output/ folder) a Postman Collection.
This behaviour can be configured by overriding the defaults and adding any of the configuration attributes:
service: my-app
plugins:
- serverless-gql-generator
gql-generator:
schema:
path: ./schema.graphql
encoding: utf-8
assumeValidSDL: true
output:
directory: ./output
s3:
bucketName: gql-output-bucket
folderPath: s3folder/path
skipLocalSaving: false
useVariables: true
maxDepth: 10
rawRequests: false
postman:
collectionName: test-name
url: https://test.com/graphql
apiKey: abc-123
Default Schema options
The plugin expects the schema to be in the root folder of the project and be called ./schema.graphql, Developers can update the configuration under gql-generator.schema in order to update the path or encoding of their schema.
gql-generator:
schema:
path: ./schema.graphql
encoding: utf-8
assumeValidSDL: true
Default Request Generation Options
Overriding the configuration on how the requests are being generated can be done by updating the following attributes under gql-generator.output.
gql-generator:
output:
directory: ./output
useVariables: true
maxDepth: 10
rawRequests: false
output.directory - path to the directory where the generated files should be stored at
output.useVariables - flag to decide if the generated requests should have inline input or dedicated variable files
output.maxDepth - maximum allowed depth for the generated requests, used to avoid infinite recursions in the requests
output.rawRequests - flag to indicate if the raw requests (.graphql files) should also be stored. This flag has to be set to true if output.postman is set to false
Default Postman Collection Configuration
The plugin will, by default, generate a Postman Collection that will be called based on ${service}-${stage} and fetch the URL and API Key from the deployed API.
gql-generator:
output:
postman:
collectionName: test-name
url: https://test.com/graphql
apiKey: abc-123
gql-generator:
output:
postman: false
Developers can override this configuration by updating the following attributes:
output.postman - can be set to false to avoid the Postman Collection being generated, for that scenario output.rawRequests will be required to be true
output.postman.collectionName - used to override the name to be used for the generated collection
output.postman.url - used to override the API endpoint, especially useful if the API has a custom domain configured or you want to use the path to the CDN or Proxy
output.postman.apiKey - used to override the API KEY to be used to authenticate the requests
Uploading files to S3
⚠
Developers or CI/CD pipelines will require credentials with write access to the desired bucket.
The output is only saved locally by default on the machine that generates the files, but there is the option to upload the files to S3 at the same time, making it even easier to share the results with other developers or teams.
gql-generator:
output:
s3:
bucketName: gql-output-bucket
folderPath: s3folder/path
skipLocalSaving: false
In order to enable the export to S3 features, developers will need to update the following configuration under gql-generator.output.s3:
output.s3.bucketName - mandatory field, has to contain the name of an existing bucket
output.s3.folderPath - used to override the folder path in S3 where the files will be stored, by default it will create the following folder structure to store the files ${service}/${stage}
output.s3.skipLocalSaving - flag to indicate if the files should be stored locally or only uploaded to S3
CLI commands
Developers might want to trigger the request generation without wanting to redeploy the API again, the plugin exposes some CLI commands to allow for that scenario.
Schema Validation
When creating or updating a Schema developers might want to validate that it's formatted appropriately.
The plugin exposes the following command to allow developers to validate the provided schema:
serverless gql-generator validate-schema
Once the above line has been executed on the terminal, it will prompt any possible issues or confirm that the schema is valid and ready to be used.
Requests generation
By default, the plugin generates all requests on every deployment, but there could be a scenario where one would like to generate them without deploying the API again.
Developers might use the following command to trigger the Request generation:
serverless gql-generator generate
Once executed, the plugin will generate all requests based on the configuration.
This command can be especially useful to confirm that the plugin is configured as expected or to generate the requests again in case the output folder has been added to .gitignore.
CI/CD integration
This plugin is easily integrated into one's CI/CD pipeline as it will be triggered automatically during the deployment process.
To access the generated files, developers might choose between:
Workflow Artifacts - Configuring the pipeline to export the artifacts generated during the process would be equivalent to generating the files locally, but the developers would need to download them from the workflow execution.
This approach is preferred for example for feature branches, where the output might change multiple times during the development.
S3 Export - Output files will be uploaded automatically to S3 for easier access and sharing.
This is the preferred approach for stable or shared branches, such as dev or main.
Conclusions
Adding the serverless-gql-generator plugin to your stack can help you and your team save time by automating the process of generating and sharing GraphQL requests.
I would love to hear about your experience using the plugin. Please use GitHub Issues to report any issues while using the plugin or requesting new features.
![[Video] DynamoDB for Relational People - AWS Community Day Turkiye 2025](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fupload%2Fv1759391824928%2Ff05a85d0-5353-4abb-bef6-3ef66e2f094f.jpeg&w=3840&q=75)
![[Webinar] DynamoDB - Common mistakes and how to optimize usage](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fupload%2Fv1722499330481%2F58678e4e-d77e-4acf-b76f-4c142504782b.png&w=3840&q=75)