Update #6 - Send test requests from API Docs, and reduce duplication with traits

Tests Requests in API Docs

We launched api-docs.io 6 weeks ago, with one goal - to be the easiest way to publish user friendly API documentation. Since then, hundreds of APIs have been published through API Docs. We've also gotten many feature requests, and three stick out:

  • The ability to make API requests straight from the documentation.
  • Code generation.
  • Collapsible side nav.

Today, we're happy to announce the immediate availability of all three features! The "Try it out" button is now available on all APIs published on api-docs.io. We understand that some publishers might not want this feature, so we have added the option to disable it when publishing from the StopLight API Designer. You will also find an option to collapse all side nav sections by default when publishing from the API Designer.

You can try it out with one of our demo APIs, like the Giphy API. This API makes use of the API Key security scheme, with a default demo api key set, which makes sending test requests extremely easy. See for yourself below!

api-docs-demo Sending a test request to the Giphy API.

Traits

Most APIs define common behaviors and responses that are supported by multiple (or all) endpoints in the API. For example, your API might handle paging behavior with "skip" and "limit" query string parameters, or define a standard set of error responses. To date, you had to duplicate these parameters and common responses for each endpoint in StopLight.

Traits allow you to define a common set of behaviors or responses, and apply them to one or more endpoints. It is an idea borrowed from the RAML spec, turned in a UI, and made available for both RAML and Swagger users (even though Swagger does not support traits! more on how that works later).

In the image below, we have defined a paged and standardErrors trait, and apply them both to the "Find Pets by status" endpoint. Notice how the existing query string and responses definitions are extended as the traits are added to the endpoint.

traits-demo Reducing duplication with traits


Soon, we'll be releasing theming, custom domains, and more, for API Docs. We also have several more de-duplication features planned for the next 4-8 weeks - stay tuned!

All of these features were suggested by our users. If you have anything you'd like to see in API Docs, or the API Designer, please let us know at [email protected]!

The StopLight Team,
Marc, Chris, Tom, and Vazha