isabella232 / spectral-postman

A sample API that retrieves constellations as an example to demonstrate features in the OpenAPI 3.0 specification.

Test APIs and lint specifications with Newman and Spectral

Cosmos is a sample API that retrieves constellations as an example to demonstrate features in the OpenAPI 3.0 specification. This project is part of a blog post about Bringing law and order to APIs with OpenAPI Specifications.

Option 1

Explore in Postman: explore this collection (generated from an OpenAPI specification file) by clicking the orange Run in Postman button below. Make sure you have a Postman environment called cosmos selected in the Postman app. There should be a key baseUrl with the value https://e8c086f7-a5c9-4752-b81f-bfac0d0dc5d2.mock.pstmn.io.

Option 2

Explore in terminal: follow the quick start below to set up this example project in your terminal or continuous integration workflow.

Quick Start

Pre-requisites for local development

1. Create a Postman account to use the Postman API to programmatically access data stored in your Postman account. You can skip this step if you're working with standalone files of your Postman collection and OpenAPI specification.
2. Make sure you have Node.js and a package manager like npm installed on your machine.

For Development

$ git clone https://github.com/postmanlabs/spectral-postman.git // clone this repo
$ cd spectral-postman // change into the new directory
$ npm install // install dependencies

Set up environment variables: Create a new file called .env located in the root of your project directory. You will need to add your own credentials and configuration information as outlined in the following steps. See the example in .env.example.

Run API tests: If you plan to run Postman tests, then update the ./bin/deploy.sh file by selecting a method of running your Postman tests. To run the second option, update your Postman collection UID, Postman environment UID, and your Postman API key in the .env file you created in the previous step.

• GET All collections (to get collection_uid)
• GET ALL environments (to get environment_uid)

Lint specification file: If you plan to lint an API specification file, then update your ./bin/deploy.sh file by selecting a method of linting your specification file. To run the second option, update your Postman API schema path and your Postman API key in the .env file you created in the first step. The configuration details for the schema path can be identified with the following steps.

• GET All workspaces (to get workspaceId)
• GET All APIs (to get apiId)
• GET All API versions (to get apiVersionId)
• GET An API version (to get schemaId)
• GET Schema (this URL contains the schema path to add to your .env file)

Run deployment script: The deployment script ./bin/deploy.sh will run the API tests and lint the specification file. If either check returns an error, the deployment script will terminate with the appropriate exit code.

$ npm run deploy