Compare commits
9 Commits
rowa97-pat
...
articles/p
| Author | SHA1 | Date | |
|---|---|---|---|
|
4387864c5a | ||
|
|
7e62571fc6 | ||
|
|
09addb857a | ||
|
|
0d53fa58f4 | ||
|
|
b41582782f | ||
|
|
62c83a8ed9 | ||
|
|
3502469fb7 | ||
|
|
2ff2b19c07 | ||
|
|
a41ac20aca |
@@ -1,11 +0,0 @@
|
||||
# Fair Billing Policy
|
||||
|
||||
Stoplight's Fair Billing Policy means you will only be charged for active users in any given billing cycle. We adopted the Fair Billing Policy because we believe you should only pay for what you use. We also wanted to avoid setting strict user limits because it can lead to workflow bottlenecks and promotes poor engineering practices.
|
||||
|
||||
## Active User
|
||||
To be considered an active user, you must perform one of the following actions:
|
||||
- Push a commit
|
||||
- Write or modify a file
|
||||
- Publish documentation
|
||||
|
||||
> If you do not perform on of these actions durign a billing cycle, you will be considered inactive, and will not count towards your user count for that billing cycle.
|
||||
@@ -1,43 +1,43 @@
|
||||
# Personal Billing Overview
|
||||
|
||||
|
||||
|
||||
## Platform Plans
|
||||
|
||||
### Open Source
|
||||
- Price: Free
|
||||
- Features:
|
||||
- API Modeling
|
||||
- Documentation
|
||||
- Mocking
|
||||
- Testing
|
||||
|
||||
### Developer
|
||||
- Price: $9/month
|
||||
- Features:
|
||||
- Unlimited Private Projects
|
||||
- Coming Soon: Github Integration
|
||||
|
||||
## Documentation Plans
|
||||
|
||||
### Basic
|
||||
- Price: Free
|
||||
- Features:
|
||||
- Unlimited Visits
|
||||
- Publish to .docs.stoplight.io
|
||||
- Docs & OpenAPI Editors
|
||||
|
||||
### Essential
|
||||
- Price: $79/month
|
||||
- Features:
|
||||
- Publish to your Domain (1 domain)
|
||||
- Theming
|
||||
- Build History & Instant Rollbacks
|
||||
|
||||
### Standard
|
||||
- Price: $179/month
|
||||
- Features:
|
||||
- Publish to your Domain (10 domains)
|
||||
- Custom CSS
|
||||
- White Label
|
||||
- Basic Auth & Auth0 Integration
|
||||
# Personal Billing Overview
|
||||
|
||||
|
||||
|
||||
## Platform Plans
|
||||
|
||||
### Open Source
|
||||
- Price: Free
|
||||
- Features:
|
||||
- API Modeling
|
||||
- Documentation
|
||||
- Mocking
|
||||
- Testing
|
||||
|
||||
### Developer
|
||||
- Price: $9/month
|
||||
- Features:
|
||||
- Unlimited Private Projects
|
||||
- Coming Soon: Github Integration
|
||||
|
||||
## Documentation Plans
|
||||
|
||||
### Basic
|
||||
- Price: Free
|
||||
- Features:
|
||||
- Unlimited Visits
|
||||
- Publish to .docs.stoplight.io
|
||||
- Docs & OpenAPI Editors
|
||||
|
||||
### Essential
|
||||
- Price: $79/month
|
||||
- Features:
|
||||
- Publish to your Domain (1 domain)
|
||||
- Theming
|
||||
- Build History & Instant Rollbacks
|
||||
|
||||
### Standard
|
||||
- Price: $179/month
|
||||
- Features:
|
||||
- Publish to your Domain (10 domains)
|
||||
- Custom CSS
|
||||
- White Label
|
||||
- Basic Auth & Auth0 Integration
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Web & Desktop App
|
||||
|
||||
|
||||
Stoplight has a desktop app! Download the appropriate version [here](https://github.com/stoplightio/desktop/releases/latest).
|
||||
Stoplight has a desktop app! Download the appropriate version [here](https://stoplight.io/download) .
|
||||
|
||||
|
||||
## Web or Local?
|
||||
|
||||
@@ -22,4 +22,4 @@ Different types of file validations are used throughout the Stoplight platform.
|
||||
|
||||
**Related Articles**
|
||||
|
||||
* [Validating Your API Spec](/modeling/modeling-with-openapi/validating-your-api-spec)
|
||||
* [Validating Your API Spec](/modeling/modeling-with-openapi/validating-your-api-sec)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Welcome to Stoplight Next!
|
||||
|
||||
Now that you have the basics on what the [Stoplight Next Platform](/platform/what-is-stoplight) is, we can go over how to get started.
|
||||
Now that you have the basics on what the [Stoplight Next Platform](/platform/introduction) is, we can go over how to get started.
|
||||
|
||||
First things first, are you using Stoplight for Personal Projects or as part of an Organization?
|
||||
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
# Permissions & Governance Overview
|
||||
|
||||
## Organizations
|
||||
|
||||
| **Organization Actions** | **Guest** | **Member** | **Administrator** | **Owner** |
|
||||
|---------------------------------|:-----------:|:------------:|:-------------------:|:-----------:|
|
||||
| Read Public Projects | X | X | X | X |
|
||||
| View Organization Collaborators | | X | X | X |
|
||||
| View Organization Teams | | X | X | X |
|
||||
| Create Projects | | X | X | X |
|
||||
| Read Private Projects | | X | X | X |
|
||||
| Write Projects | | | X | X |
|
||||
| Manage Collaborators | | | X | X |
|
||||
| Manage Teams | | | X | X |
|
||||
| Manage Organization Settings | | | | X |
|
||||
| Manage Organization Billing | | | | X |
|
||||
| Delete Organization | | | | X |
|
||||
|
||||
## Teams
|
||||
|
||||
| **Team Actions** | **Member** | **Administrator** | **Owner** |
|
||||
|-------------------------|:------------:|:-------------------:|:-----------:|
|
||||
| View Team Collaborators | X | X | X |
|
||||
| Add Team to Projects | X | X | X |
|
||||
| Manage Team Collaborators | | X | X |
|
||||
| Manage Team Settings | | X | X |
|
||||
| Delete Team | | | X |
|
||||
|
||||
## Projects
|
||||
|
||||
| **Project Actions** | **Read** | **Write** | **Administrator** |
|
||||
|------------------------------|:--------:|:---------:|:-----------------:|
|
||||
| Read Project | X | X | X |
|
||||
| Write Project | | X | X |
|
||||
| Manage Project Collaborators | | | X |
|
||||
| Delete Project | | | X |
|
||||
@@ -1,6 +1,6 @@
|
||||
# Blocks
|
||||
|
||||
|
||||
|
||||
|
||||
## What
|
||||
Blocks are the micro-level building blocks of Hubs. They house multiple forms of content and allow for simple restructuring and modification.
|
||||
@@ -22,6 +22,12 @@ Blocks are the micro-level building blocks of Hubs. They house multiple forms of
|
||||
* An upper level block for organizing text within tabs
|
||||
### Callout
|
||||
* A text block with color for emphasis
|
||||
### Hero
|
||||
* A large stylized text block with additional functionality typically found on landing pages
|
||||
### Bar List
|
||||
* A navigational block composed of bars with buttons
|
||||
### Card List
|
||||
* A navigational block composed of cards with text, buttons, and optional images
|
||||
### HTML
|
||||
* Include arbitrary HTML in your hubs when the other base block types don't quite do the trick
|
||||
|
||||
@@ -29,7 +35,7 @@ Blocks are the micro-level building blocks of Hubs. They house multiple forms of
|
||||
**Related Articles**
|
||||
- [Documentation with Hubs](/documentation/introduction)
|
||||
- [Routing](/documentation/getting-started/routing)
|
||||
- [Headers](/documentation/getting-started/header-footer)
|
||||
- [Headers & Footers](/documentation/getting-started/header-footer)
|
||||
- [Pages](/documentation/getting-started/pages)
|
||||
- [Subpages](/documentation/getting-started/subpages)
|
||||
- [Referencing Other Data Sources](/documentation/referencing-other-data-sources)
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
# Custom CSS
|
||||
|
||||
|
||||
|
||||
## What
|
||||
|
||||
Want to add some style and flair to your documentation? Add your own custom CSS to enhance your Hub’s look and feel. Below are some of the classes you can modify:
|
||||
|
||||
```
|
||||
.Hub
|
||||
.HubHeader
|
||||
.HubHeader-section
|
||||
.HubHeaderItem.is-active
|
||||
.HubHeaderItem-name
|
||||
.HubMain
|
||||
.HubSidebar-overlay
|
||||
.HubSidebar-wrapper
|
||||
.HubSidebar
|
||||
.HubSidebar-inner
|
||||
.HubBranding
|
||||
.HubPage-wrapper
|
||||
.HubPage
|
||||
.HubPage-inner
|
||||
.HubPage-content
|
||||
.HubPageCrumbs
|
||||
.HubPageCrumb
|
||||
.HubPageBody
|
||||
.HubBlock
|
||||
.HubPageFooter
|
||||
```
|
||||
|
||||
## How
|
||||
|
||||
1. Select the Hub you wish to modify
|
||||
2. Select the **Design View**
|
||||
3. Click on **Theme** in the top toolbar
|
||||
4. Select **Custom CSS** in the bottom left
|
||||
5. Input CSS in the text area at the bottom of the page
|
||||
6. Input CSS in the generated **theme** file (optional)
|
||||
7. In publishing, check the **Custom CSS** box under **Advanced** to apply the Custom CSS to that Hub when published
|
||||
|
||||
>After accessing Custom CSS, a **theme** file will be generated under Documentation in the file explorer. After making changes to your CSS, make sure to save the **theme** file.
|
||||
|
||||
---
|
||||
**Related Articles**
|
||||
- [Theming](/documentation/design/theming)
|
||||
@@ -1,56 +0,0 @@
|
||||
# OAuth for Hubs
|
||||
|
||||
## What
|
||||
|
||||
OAuth provides a level of security to your documentation to restrict access to it. Enabling OAuth in Hubs can be accomplished through two different methods: via Modeling or directly into the Hubs code.
|
||||
|
||||
> Stoplight supports OAuth 1.0 and 2.0
|
||||
|
||||
## How
|
||||
|
||||
### Modeling
|
||||
|
||||
|
||||
|
||||
1. Create a new Modeling file or select an existing one referenced by the Hub you wish to modify
|
||||
|
||||
> If you are creating a new Modeling file, make sure to reference it in your Hub
|
||||
|
||||
2. Next to **Security** in the left-middle toolbar, Add a Security Scheme by clicking the **+**
|
||||
3. Input a **key**
|
||||
4. Select oauth2 under **type**
|
||||
5. Select **accessCode** under OAuth **flow**
|
||||
6. Select an **authorization url**
|
||||
7. Select a **token url**
|
||||
8. **Add Scope** (optional)
|
||||
9. Add a **Security scheme description** (optional)
|
||||
|
||||
### Hubs
|
||||
|
||||
|
||||
|
||||
1. Select the Hub you wish to modify
|
||||
2. Select **Code View**
|
||||
3. Add the following lines of code to your Hub:
|
||||
|
||||
```
|
||||
|
||||
"config": {
|
||||
"http": {
|
||||
"oauth2": {
|
||||
"credentials": {
|
||||
"authorize_url": "insert authorize url here",
|
||||
"access_token_url": "insert access token url here",
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
**Related Articles**
|
||||
|
||||
- [Digital Oceans: Introduction to OAuth2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)
|
||||
- [Security Schemes](/modeling/modeling-with-openapi/security-schemes)
|
||||
|
||||
@@ -21,13 +21,10 @@ Texture applies a texture to your header.
|
||||
## How
|
||||
1. Select the **Hub** you wish to modify
|
||||
2. Select the **Design View**
|
||||
3. Click on **Theme** at the top of the screen
|
||||
4. Select a pre-selected color or choose your own color with the eyedropper
|
||||
5. Select a texture
|
||||
|
||||
---
|
||||
|
||||
**Related Links**
|
||||
- [Custom CSS](/documentation/design/custom-css)
|
||||
3. Click on **Settings** at the top of the screen
|
||||
4. Select **Theme** in the sidebar
|
||||
5. Select a pre-selected color or choose your own color with the eyedropper
|
||||
6. Select a texture
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
# Variables in Hubs
|
||||
|
||||
## What
|
||||
|
||||
Inputting variables in API documentation whenever you consume them can quickly become a tedious time sink. The same pain point applies to people consuming your documentation. Inputting an API key everytime you want to send HTTP Requests to test endpoints is time better spent elsewhere. Stoplight removes this obstacle by storing variables in your local browser. Once you input a variable, it populates the rest of your docs, no duplication, no problems.
|
||||
|
||||
## How
|
||||
|
||||
You can specify variables in your docs by adding them at the specification level or directly into Hubs.
|
||||
|
||||
### Modeling Method
|
||||
|
||||
|
||||
|
||||
1. Select the modeling file you wish to modify
|
||||
2. Create a new **security scheme**
|
||||
1. Input a **key** (required, must be unique in this specification)
|
||||
2. Select a **type** of security scheme
|
||||
3. Select a location for the security scheme under **in**
|
||||
4. Input a **name**
|
||||
3. Reference the specification in your Hub
|
||||
|
||||
---
|
||||
|
||||
### Hubs Method
|
||||
|
||||
|
||||
|
||||
1. Select the Hub you wish to modify
|
||||
2. Create a **HTTP Request Maker** block
|
||||
3. Select the **Headers** tab
|
||||
4. Click **Add Header**
|
||||
5. Input a **header name**
|
||||
6. Input a **header value**
|
||||
|
||||
***
|
||||
|
||||
**Related**
|
||||
|
||||
* [Security Schemes Overview](/modeling/modeling-with-openapi/security-schemes)
|
||||
@@ -1,54 +0,0 @@
|
||||
# Stoplight Classic to Stoplight Next Migration Notes
|
||||
|
||||
## Platform
|
||||
|
||||
| | **Stoplight Classic (v2)** | **Stoplight Next (v3)** |
|
||||
| :---------------------- | :---------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|
||||
| **File Types** | RAML and YAML | YAML |
|
||||
| **Commits** | Basic Commit System | [Platform backed by Git, all files are Git Repos and have full Git commit support](/platform/projects/git-repo) |
|
||||
| **Collaborative Space** | Workspaces | [Projects](/platform/projects/creating-a-project), [Organizations](/platform/organizations/create-org), and [Teams](/platform/organizations/teams/create-team) |
|
||||
| **Billing** | Individual Billing | [Individual Billing](/platform/getting-started/billing/plans-overview), [Organization Billing](/platform/getting-started/billing/organization-plan-overview), and [Fair Billing Policy](/platform/getting-started/billing/fair-billing) |
|
||||
| **Swagger Extensions** | Not supported | Supported |
|
||||
| **Change History** | Basic Commit History | [Full Commit History Backed by Git](/platform/editor-basics/change-history) |
|
||||
| **Project Visibility** | Private Projects | [Private and Public Organizations and Projects](/platform/projects/visibility) |
|
||||
| **Guest Role** | Guests (read-only) count towards your team size | [50 Guest limit that doesn't count towards your team size](/platform/getting-started/billing/fair-billing) |
|
||||
| **Ref Builder** | Not supported | [Supported](/documentation/referencing-other-data-sources) |
|
||||
| **Access Tokens** | Not supported | Supported |
|
||||
| **Code View** | Not supported | [Supported](/platform/editor-basics/read-design-code-view) |
|
||||
|
||||
## Modeling
|
||||
|
||||
| | **Stoplight Classic (v2)** | **Stoplight Next (v3)** |
|
||||
| :----------------------- | :------------------------: | :---------------------------------------------------------------------------------------------: |
|
||||
| **Shared Specification** | Traits | [Shared Models and Parameters](/modeling/modeling-with-openapi/shared-parameters-and-responses) |
|
||||
| **Grouping** | Grouping | [Hubs Ref Builder](/documentation/referencing-other-data-sources) |
|
||||
| **Documentation Design** | Modeling | [Hub](/documentation/introduction) |
|
||||
| **API Discovery** | Supported | Coming Soon |
|
||||
| **Bulk Editing** | Supported | [Code View Editor](/platform/editor-basics/read-design-code-view) |
|
||||
|
||||
## Hubs
|
||||
|
||||
| | **Stoplight Classic (v2)** | **Stoplight Next (v3)** |
|
||||
| :------------------------- | :------------------------: | :------------------------------------------------------------------------------------------------------------------------------: |
|
||||
| **Documentation Produced** | API Reference | API Reference, Supplementary Documentation, and Auxillary Documentation |
|
||||
| **Linking** | SRN | Markdown |
|
||||
| **Routes** | Slug | [Markdown](/documentation/getting-started/routing) |
|
||||
| **Hiding Models** | Supported | Coming Soon |
|
||||
| **Authentication** | Basic Auth and OAuth 2.0 | [Basic Auth, Auth0, OAuth 2.0, and SAML with multiple security scheme support](/modeling/modeling-with-openapi/security-schemes) |
|
||||
| **Workflow** | Creation through Modeling | [Standalone Documentation Tool](/documentation/introduction) (Hubs) |
|
||||
| **Custom Domain** | Email Support | Automated |
|
||||
|
||||
## Prism
|
||||
|
||||
| | **Stoplight Classic (v2)** | **Stoplight Next (v3)** |
|
||||
| :--------------------- | :------------------------------------------------------------------: | :----------------------------------------------------------: |
|
||||
| **HTTP Requests** | Logs HTTP Requests | Coming Soon |
|
||||
| **Prism Instances** | Every version supported by Mock Server and Proxy Server | [Unlimited amount of Prism Instances](/mocking/introduction) |
|
||||
| **Javascript Runtime** | [API](https://help.stoplight.io/prism/runtime-reference/api) | [API](/mocking/javascript-runtime) |
|
||||
| **Prism Command Line** | [Commands](https://help.stoplight.io/prism/getting-started/commands) | Commands Changed |
|
||||
|
||||
## Scenarios
|
||||
|
||||
| | **Stoplight Classic (v2)** | **Stoplight Next (v3)** |
|
||||
| :---------- | :------------------------: | :---------------------------------------------------: |
|
||||
| **Testing** | Not Available | [Integrated into the platform](/testing/introduction) |
|
||||
@@ -43,7 +43,7 @@ There are many benefits to using JSON, some of which include:
|
||||
be written in YAML, so either format can be used to write OpenAPI specifications
|
||||
|
||||
* It can be used to link files together through [JSON
|
||||
references](/modeling/modeling-with-openapi/referencing-another-api-spec), making it easy to break up large documents
|
||||
references](/modeling/introduction/modeling-with-openapi/referencing-another-api-spec), making it easy to break up large documents
|
||||
into smaller, more focused documents
|
||||
|
||||
Whether you are modeling an API, creating a Prism Collection, or writing
|
||||
|
||||
@@ -30,4 +30,4 @@ There are a few ways to get started designing your API with the Stoplight design
|
||||
- Create an API from scratch [Using the CRUD Builder](/modeling/modeling-with-openapi/using-the-crud-builder)
|
||||
- [Reference another API Spec](/modeling/modeling-with-openapi/referencing-another-api-spec)
|
||||
- [Send HTTP Requests](/modeling/modeling-with-openapi/sending-http-requests) to an existing API Spec
|
||||
- [Validate your API Spec](/modeling/modeling-with-openapi/validating-your-api-spec)
|
||||
- [Validate your API Spec](/modeling/modeling-with-openapi/validating-your-api-sec)
|
||||
|
||||
@@ -31,5 +31,4 @@ Use the HTTP Request Maker to send requests to the endpoints defined in your spe
|
||||
|
||||
---
|
||||
**Related Articles**
|
||||
|
||||
- [Using Environment Variables](/testing/using-variables/environment)
|
||||
[Using Environment Variables](/testing/using-variables/environment)
|
||||
|
||||
@@ -1,43 +0,0 @@
|
||||
# Technical Writer Playbook
|
||||
|
||||
Documenting an API is crucial to its success but can be extremely time consuming. Here at Stoplight, we believe documentation should be beautiful, clean, and robust while maintaining a streamlined turnaround time. We’ve created a holistic documentation tool, Hubs, to address some of the problems our users were facing including:
|
||||
|
||||
- Documenting Endpoints
|
||||
- Testing Endpoints
|
||||
- Creating Non-Reference Documentation
|
||||
- Managing Content
|
||||
- External and Internal Referencing
|
||||
- Design and Style
|
||||
|
||||
|
||||
## Documenting Endpoints
|
||||
The most key component to API Documentation are its endpoints. To that end, we created a reference builder that allows you to [“power pages”](/documentation/referencing-other-data-sources) with your specification as you see fit. When you power a page or subpage with your specification, the endpoints are automatically documented and styled for legibility and aesthetic design.
|
||||
|
||||
## Testing Endpoints
|
||||
Testing endpoints is a valuable tool for anyone who wants to consume your API. Users want to know that your API functions properly before they commit to using it. To address this problem, we created [“Try it Out,” an HTTP Request Maker](/modeling/modeling-with-openapi/sending-http-requests). Try it Out allows you to send HTTP Requests to your API to test out its endpoints under any number of different conditions. You can customize Try it Out with security schemes, variables, headers, queries, and it even generates code in various programming languages.
|
||||
|
||||
## Creating Non-Reference Documentation
|
||||
Great documentation is more than just API endpoints. Guides, tutorials, and other supplemental information enhance your users experience by providing them with all the information they need to access your API and your product. We broadened Hubs scope to accomodate all product documentation needs. You can easily build out your content within [Blocks](/documentation/blocks), a number of flexible content structures that can house a number of different forms of content including markdown, images, code snippets, and much more.
|
||||
|
||||
## Managing Content
|
||||
Organizing a complex APIs endpoints and supplemental information can be a challenging task. Some specification can have hundreds of endpoints with supplemental information throughout. To assist with organizing content, we created an overview of all your pages, subpages, and their connections called “Table of Contents”. With a bird’s eye view of your content, you can easily organize and manage your content through drag drop functionality.
|
||||
|
||||
## External and Internal Referencing
|
||||
To accomodate a larger variety of writing workflows, we expanded the capabilities of [Powering a Page](/documentation/referencing-other-data-sources) to allow for more files internally and externally to be referenced. You can now easily reference internal or external specifications, and Markdown, YAML, JSON, and Scenario files.
|
||||
|
||||
## Design and Style
|
||||
We wanted to create a new, beautiful, minimalistic, efficient design for less design-oriented individuals while allowing for customization. Hubs was designed to display your documentation in a neat, efficient structure, designed specifically for displaying the real beauty, your API. On the other hand, we didn’t want to stifle the creativity that goes into documentation design so we added in [theming](/documentation/design/theming) and [custom CSS](/documentation/design/custom-css). We also made it easier to add navigation, different kinds of content, and a more robust search.
|
||||
|
||||
---
|
||||
Related Links
|
||||
- [Documentation with Hubs](/documentation/introduction)
|
||||
- [Routing](/documentation/getting-started/routing)
|
||||
- [Headers](/documentation/getting-started/header-footer)
|
||||
- [Pages](/documentation/getting-started/pages)
|
||||
- [Subpages](/documentation/getting-started/subpages)
|
||||
- [Blocks](/documentation/blocks)
|
||||
- [Referencing Other Data Sources](/documentation/referencing-other-data-sources)
|
||||
- [Publishing](/documentation/publishing)
|
||||
- [Theming](/documentation/design/theming)
|
||||
- [Custom CSS](/documentation/design/custom-css)
|
||||
|
||||
0
articles/playbooks/writers.md
Normal file
0
articles/playbooks/writers.md
Normal file
@@ -1,59 +0,0 @@
|
||||
# Introduction
|
||||
|
||||
Prism is a proxy and API server toolkit that helps you test, mock, validate, and orchestrate your online applications. We rebuilt Prism from the ground up to be performant, powerful, and programmable while still being practical. Prism enables teams to work in parallel and iterate faster with less errors. The Stoplight Platform integrates tightly with Prism to generate test coverage of your API automatically, build tests visually, and create mock and contract servers instantly.
|
||||
|
||||
Prism has first class support for the OpenAPI Specification (aka OAS) and Stoplight Scenarios. OAS is machine readable documentation of your API that Prism can read and understand. Scenarios tell Prism how to orchestrate your API. When you use them together you can easily assert, transform, and validate your API against your OAS. Prism also allows your front-end team to work in tandem with your back-end team. While the back-end team implements your API, your front-end teams can implement against a mock server that can return static examples, dynamic data, or replay actual traffic from your API.
|
||||
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
* Act as a mock server, routing incoming requests to example responses, or dynamically generating examples on the fly
|
||||
* Act as a transformation layer, manipulating incoming requests and outgoing responses
|
||||
* Act as a validation layer, validating incoming requests, and outgoing responses
|
||||
* Contract test your APIs
|
||||
* Extend existing APIs with new endpoints or capabilities
|
||||
* Act as a system-wide proxy, blocking traffic to particular websites or endpoints
|
||||
|
||||
## Conduct vs Serve
|
||||
|
||||
Conduct and Serve are important concepts to understand when using Prism.
|
||||
|
||||
* Conduct is an isolated scenario run. You tell Prism what scenarios you want to run, give it an environment to run against, and Prism will generate a report of the run
|
||||
|
||||
* Serving, on the other hand, is a long running instance of Prism that applies scenarios to HTTP traffic
|
||||
|
||||
### Conduct Use Cases
|
||||
|
||||
1. Debugging your API implementation or specification
|
||||
2. Integrating with your CI/CD Environment: Catch bugs before they get to your actual API Consumers
|
||||
3. Webhooks: Generate your OAS from code, automatically upload it to Stoplight
|
||||
|
||||
|
||||
|
||||
### Serve Use Cases
|
||||
|
||||
1. Mocking back one or more specifications: Useful to help teams work in parallel and simplify testing dependencies.
|
||||
2. Validating live traffic between your client/backend.
|
||||
3. Your API, your workflow, your Prism. Prism is very flexible. You can easily create an instance that will record your API traffic, save it to S3, and then create another instance that will replay that API traffic.
|
||||
|
||||
|
||||
|
||||
### Stoplight Prism Helpers
|
||||
|
||||
The [Prism Helpers](https://next.stoplight.io/stoplight/prism) project is a collection of scenarios, specifications, and Prism instances that illustrate how to use Prism effectively. Please go [here](https://community.stoplight.io) and let us know what you would like to see.
|
||||
|
||||
---
|
||||
|
||||
**Related Articles**
|
||||
|
||||
* [Javascript Runtime](/mocking/javascript-runtime)
|
||||
* [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
|
||||
* [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
|
||||
* [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
|
||||
* [Using Variables Overview](/testing/using-variables/overview)
|
||||
* [$$.env (Environment)](/testing/using-variables/environment)
|
||||
* [$.ctx(Context)](/testing/using-variables/context)
|
||||
* [Sending HTTP Requests](/testing/sending-http-requests/overview)
|
||||
* [Contract Testing](/testing/leveraging-openapi/contract-testing)
|
||||
* [Integrating in Continuous Integration](/testing/continuous-integration/overview)
|
||||
61
articles/prism/overview.md
Normal file
61
articles/prism/overview.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Mocking with Prism
|
||||
|
||||
Prism is a performant, dependency free server, built specifically to work with web APIs.
|
||||
|
||||
### Features
|
||||
- Act as a mock server, routing incoming requests to example repsonses, or dynamically generating examples on the fly.
|
||||
- Act as a transformation layer, manipulating incoming requests and outgoing responses.
|
||||
- Act as a validation layer, validating incoming requests and outgoing responses.
|
||||
- Contract test your APIs, given an OAS(Swagger 2) file.
|
||||
- Log all or a subset of traffic to configurable locations.
|
||||
- Extend existing APIs with new endpoints or capabilites.
|
||||
- Act as a system-wide proxy, blocking traffic to particular websites or endpoints.
|
||||
|
||||
### Simplicity Redefined
|
||||
Run it anywhere. It runs on OS X, Windows, and Linux, with no external dependencies. It is a single, self-contained binary file, that you can easily run from your terminal with a single command.
|
||||
|
||||
## Getting Started
|
||||
|
||||
#### macOS and Linux
|
||||
|
||||
```# Install Prism
|
||||
curl https://raw.githubusercontent.com/stoplightio/prism/master.install.sh | sh
|
||||
```
|
||||
|
||||
#### Windows
|
||||
Download the appropriate binary from [here](https://github.com/stoplightio/prism/releases). Unzip the binary file, then navigate in your terminal to the folder where you extracted Prism.
|
||||
|
||||
### Run a Simple Mock Server
|
||||
Prism understands OAS(Swagger 2), so let's get started by spinning up a quick mock server for the popular Petstore API. To do this, run the following command in your terminal:
|
||||
|
||||
```# os x / linux
|
||||
prism run --mock --list --spec http://petstore.swagger.io/v2/swagger.json
|
||||
|
||||
# windows
|
||||
path/to/prism.exe run --mock --list --spec http://petstore.swagger.io/v2/swagger.json
|
||||
```
|
||||
|
||||
Here, you are using the "run" command to run a server based on the spec file passed in via the --spec argument. The spec location can be the filepath to a file on your computer, or the URL to a publicly hosted file. The mock argument tells Prism to mock all incoming requests, instead of forwarding them to the API host described in the spec file. The list argument is a convenience, and tells Prism to print out the endpoints in the spec on startup.
|
||||
|
||||
Prism starts on port 4010 by default - try visiting ```http://localhost:4010/v2/pet/findByStatus``` in your browser. This is one of the endpoints described in the petstore spec you passed in. You'll notice that it returns an error about a required query string parameter "status". This is the automatic request validation at work! The swagger spec specifies that a query string parameter names "status" is required for this endpoint so Prism simulates a 400 response for you. Reload the page with a query string parameter, and you will see the dynamically generated mock response ```http://localhost:4010/v2/pet/findByStatus?status=available```.
|
||||
|
||||
Tada! With a single command you have started a validating, dynamically mocking version of the Swagger petstore API.
|
||||
|
||||
### Run some Contract Tests
|
||||
|
||||
Prism consumes OAS(Swagger 2) files. OAS provides the contract for your API. If your OAS file contains the x-tests extension (generated automatically if you use the Stoplight app to manage your OAS and tests) then you can run tests with Prism.
|
||||
|
||||
Check out [this specification](https://goo.gl/jniYmw). If you scroll past all the regular OAS properties, you will notice a ```x-tests``` extension near the bottom of the file. Inside of that property, we have a few test cases defined. This OAS file, along with its tests, is managed in the Stoplight app (we export our API from within the app to produce this file).
|
||||
|
||||
#### To Run the Contract Tests
|
||||
```
|
||||
# os x / linux
|
||||
prism test --spec https://goo.gl/jniYmw
|
||||
|
||||
# windows
|
||||
path/to/prism.exe test --spec https://goo.gl/jniYmw
|
||||
```
|
||||
|
||||
You should see some nice output to your terminal detailing the tests and assertions that are run. These tests take our OAS contract and apply it to your API. They act as a sort of sync manager.
|
||||
|
||||
> If a test fails, it means one of two things - your API is broken or, our OAS contract is out of date / incorrect
|
||||
@@ -120,11 +120,10 @@ var data = SL.schema.generate(contract);
|
||||
|
||||
#### Find Operation
|
||||
|
||||
The code snippet below describes the Stoplight representation of an HTTP operation. It is loosely based on OAS 3. You can find more descriptions of some of the properties described below [here](https://swagger.io/specification/#operationObject).
|
||||
|
||||
```js
|
||||
/**
|
||||
*
|
||||
* This describes the Stoplight representation of an HTTP operation. It is loosely based on OAS 3. You can find more descriptions of some of the properties described below here: https://swagger.io/specification/#operationObject.
|
||||
*
|
||||
* @typedef {Object} Operation
|
||||
* @property {string} method
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
# Git Repositories
|
||||
|
||||
## What
|
||||
The Stoplight Platform is built on top of Git. This means that all your projects are Git repositories and that our platform benefits from all the additonal functionality provided by Git. To access the Git funtionality, you will need to clone your Git repository by generating an Access Token.
|
||||
|
||||
> You can also use Access Tokens to access the Stoplight API, authenticate Prism in a continuous integration enviornment, and access the underlying Git repositories for projects. You can make this part of your Git workflow, add it to scripts, or your CI/CD process
|
||||
|
||||
## Who
|
||||
|
||||
If you have write access to a project, you will be able to:
|
||||
* Pull projects via Git
|
||||
* Commit to projects via Git
|
||||
* Push changes to projects via Git
|
||||
|
||||
If you have read access to a project, you will be able to:
|
||||
* Pull your project via Git
|
||||
|
||||
## How to Clone Your Stoplight Git Repository
|
||||
|
||||
1. Select the **Settings** tab on the platform homepage
|
||||
2. Select **Access Tokens** from the left
|
||||
|
||||
|
||||
|
||||
3. Create a token to access projects that your Stoplight account has proper permissions for (These permissions match the ones in the Stoplight UI)
|
||||
|
||||
> You can name your token whatever you want. Once you have created the token, copy it, and only store it in a safe location. Once you close the window, you will not see it again
|
||||
|
||||
3. On your machine, store your access token as an environmental variable (recommended)
|
||||
|
||||
For example, on Mac/Linux:
|
||||
|
||||
```
|
||||
export STOPLIGHT_TOKEN="1234567890"
|
||||
```
|
||||
|
||||
4. You can then `git clone` the repo, replace `{stoplight-username}`, `{username}`, and `{project-name}` with the appropriate information:
|
||||
|
||||
```
|
||||
git clone https://{stoplight-username}:$STOPLIGHT_TOKEN@git.stoplight.io/{username}/{project-name}.git
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
git clone https://taylor:$STOPLIGHT_TOKEN@git.stoplight.io/taylor/test-new.git
|
||||
```
|
||||
|
||||
> If the project is associated with an organization and not a personal project, replace `username` with `organization-name`
|
||||
|
||||
5. Now you can make changes to your files, commit, and push to your master branch. You can see these changes in the Stoplight UI as well as the "History of Changes"
|
||||
|
||||
> Remember: You will only see changes on the master branch in the UI at this time.
|
||||
|
||||
|
||||
---
|
||||
**Related Articles**
|
||||
- [Change a Project Member's Role](/platform/projects/change-a-members-role)
|
||||
- [Make Your Project Private/Public](/platform/projects/visibility)
|
||||
- [Invite People to Organization](/platform/organizations/invite-people)
|
||||
- [Add People to a Team](/platform/organizations/teams/add-people)
|
||||
@@ -1,4 +1,4 @@
|
||||
# Making Your Project Private & Public
|
||||
## Making Your Project Private & Public
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -19,4 +19,4 @@
|
||||
**Related Articles**
|
||||
- [Delete an Organization](/platform/organizations/delete-org)
|
||||
- [Transfer Ownership of a Team](/platform/organizations/teams/transfer-ownership)
|
||||
|
||||
- [Delete a Team](/platform/organizations/teams/delete)
|
||||
|
||||
@@ -86,6 +86,7 @@ Any validation errors will automatically be added to the test results.
|
||||
---
|
||||
**Related Articles**
|
||||
- [Testing Introduction](/testing/introduction)
|
||||
- [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
|
||||
- [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
|
||||
- [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
|
||||
- [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
|
||||
@@ -93,4 +94,4 @@ Any validation errors will automatically be added to the test results.
|
||||
- [$$.env (Environment)](/testing/using-variables/environment)
|
||||
- [$.ctx(Context)](/testing/using-variables/context)
|
||||
- [Sending HTTP Requests](/testing/sending-http-requests/overview)
|
||||
|
||||
- [Referencing other Scenarios](/testing/referencing-other-scenarios/overview)
|
||||
|
||||
@@ -24,10 +24,11 @@ API tests provide insight into how your API behaves under certain scenarios and
|
||||
|
||||
Microservices and serverless architecture have made it easier than ever to iterate quickly. The downside of rapid development is an increase in bugs and technical debt, making projects harder to manage without a proper testing solution. It is critical to have a comprehensive test suite to allow teams to test the API during development.
|
||||
|
||||
>Stoplight makes it easy to create a full suite of tests by providing [Environment](/testing/using-variables/environment) and [Context variables](/testing/using-variables/context), and the ability to reference other scenarios to accelerate test generation and reduce duplication.
|
||||
>Stoplight makes it easy to create a full suite of tests by providing [Environment](/testing/using-variables/environment) and [Context variables](/testing/using-variables/context), and the ability to [reference other scenarios](/testing/referencing-other-scenarios/overview) to accelerate test generation and reduce duplication.
|
||||
|
||||
---
|
||||
**Related Articles**
|
||||
- [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
|
||||
- [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
|
||||
- [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
|
||||
- [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
|
||||
@@ -35,7 +36,8 @@ Microservices and serverless architecture have made it easier than ever to itera
|
||||
- [$$.env (Environment)](/testing/using-variables/environment)
|
||||
- [$.ctx(Context)](/testing/using-variables/context)
|
||||
- [Sending HTTP Requests](/testing/sending-http-requests/overview)
|
||||
- [Contract Testing](/testing/leveraging-openapi/contract-testing)
|
||||
- [Referencing other Scenarios](/testing/referencing-other-scenarios/overview)
|
||||
- [Contract Testing](testing/leveraging-openapi/contract-testing)
|
||||
- [Integrating in Continuous Integration](/testing/continuous-integration/overview)
|
||||
- [Integrating with Jenkins](/testing/continuous-integration/jenkins)
|
||||
- [Integrating with Travis](/testing/continuous-integration/travis)
|
||||
|
||||
@@ -7,7 +7,7 @@ way is through the Stoplight editor.
|
||||
|
||||
|
||||
> If you haven't created your first scenario yet, please [do so before
|
||||
> continuing](/testing/introduction)
|
||||
> continuing](testing/introduction)
|
||||
|
||||
Scenarios in Stoplight are composed of three different levels:
|
||||
|
||||
|
||||
@@ -63,11 +63,11 @@ You can also run a contract test against a specific upstream URL with the
|
||||
prism validate --spec /path/to/my/spec.json --upstream http://localhost:8080
|
||||
```
|
||||
|
||||
For more information on contract testing and how it can be used, see [here](/testing/leveraging-openapi/contract-testing).
|
||||
For more information on contract testing and how it can be used, see [here](testing/leveraging-openapi/contract-testing).
|
||||
|
||||
---
|
||||
**Related Articles**
|
||||
|
||||
- [Testing Introduction](/testing/introduction)
|
||||
- [Contract Testing](/testing/leveraging-openapi/contract-testing)
|
||||
- [Contract Testing](testing/leveraging-openapi/contract-testing)
|
||||
- [Integrating in Continuous Integration](/testing/continuous-integration/overview)
|
||||
|
||||
@@ -110,6 +110,7 @@ platforms.
|
||||
---
|
||||
**Related Articles**
|
||||
- [Testing Introduction](/testing/introduction)
|
||||
- [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
|
||||
- [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
|
||||
- [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
|
||||
- [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
|
||||
|
||||
|
Before Width: | Height: | Size: 871 KiB After Width: | Height: | Size: 871 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 2.0 MiB After Width: | Height: | Size: 2.3 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.4 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 9.7 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 130 KiB |
Reference in New Issue
Block a user