Welcome!

This is a quick little starter hub for your new project.

  1. This project is meant to work with the API running at http://todos.stoplight.io.
  2. This hub pulls together data from several other sources (like the main.oas2 file in this project) to render its content.
  3. Open the project file explorer by clicking the file icon in the left gutter.
  4. Click through the files to view their editors and make changes. Each file has an extension that indicates its type.
  5. Stoplight currently supports 5 extensions:
    • .hub: Technical documentation.
    • .oas2: API Design + Modeling.
    • .scenarios: API Testing + Orchestration.
    • .prism: API Mocking + Validation.
    • .md: Snippets of documentation.
    • .oas3: Coming Soon!

If you make changes to any of the files, don’t forget to click the “Save” button, located in the top left of the editors.

Quickstart

There are various files displayed in the file explorer to the left, organized by type (click file button in gutter if you don’t see the list).

  1. Modeling: Get started with our OAS/Swagger editor.
  2. Scenarios: Create API tests (and contract tests!) with our Scenarios editor.
  3. Prism: Create different types of servers (mocking, validation, etc) with Prism.

Bonus: Connect your files together with references to supercharge them!

Testing

  • The tests.scenarios in this project leverages the main.oas2 file to power its contract testing.
  • NOTE: The todo-partial model in the main.oas2 file intentially includes a required “user” property that will cause the tests to fail. This is because the actual todos.stoplight.io API does not return a user property. Try it out by navigating to the tests.scenarios file and running the collection!

Modeling Features

  • This project includes two OAS2 (Swagger 2) files - common.oas2 and main.oas2.
  • This main.oas2 leverages the JSON Schema allOf property (inheritance), shared parameters (common query string), and shared responses (common error codes).
  • This main.oas2 specification references data defined in the common.oas2 specification. Check out the “user” property in the todo-full model. It references the common.oas2 file in this project, but could easily reference a file in another project. This lets you build up shared libraries of data for your organization.
  • You can quickly send requests to the To-dos API by clicking the “HTTP Request Maker” tab at the bottom of the modeling editor.
  • While the HTTP Request Maker is open, you can navigate through operations in the editor sidebar to quickly update the request from your OAS specification.
  • If you have prism files in this project, you can select their host to send requests to them instead. Try sending a request to the mock.prism instance, its running a mock API based on this specification!
Edit This Hub

Click the “Design” button in the top left. Note that you must have write access to this project to see the button.

Because cats are fun, here’s a cat! This also demonstrates a more complicated widget - text and http blocks nested inside of a tabs block.

Get Cat Gif
Language
Library
curl --request GET \
  --url 'http://thecatapi.com/api/images/get?format=src&type=gif'