How to Generate 2,000 Lines of Specification Code in 60 Seconds

So, you have a pre-existing web API, with 1–1000 endpoints, and no OAI (Swagger) / RAML / JSON Schema / {insert api spec here} defined for it. How do you get these endpoints described and covered by one or more of these specifications?

Option 1 Manually write the spec for each endpoint. This is time consuming, error prone, and it does not scale. It sucks.

Option 2 Manually define each endpoint in a higher level designer, like StopLight, and then export to a specification. Less time consuming and error prone, but still not ideal.

Option 3 Use the StopLight API Designer + Prism Proxy to automatically generate endpoint definitions, simply by sending HTTP traffic to your API.

In this post, we’re going to describe the basics of option 3. The StopLight API Designer + Prism Proxy combo is the fastest, and most effective, method of generating Swagger / RAML / JSON Schema for a pre-existing API.

First, a short video of it in action, automatically discovering/generating the Ghost blogging platform’s API.

So…

We just generated ~2,000 lines of Swagger/RAML specification + JSON Schemas, in less than 60 seconds.

Speaking of time.. in the time it takes you to read the text below, you could complete a short interactive tutorial in the API Designer, that guides you through discovering an endpoint.

How? We are sending HTTP traffic through the local instance of the Prism API Proxy. By default, the proxy runs on http://localhost:4010. Back in the API Designer, for our development environment, we have defined the API Host as http://localhost:2368. This is where the Ghost blogging platform is running on our computer.

When a request comes into the proxy (localhost:4010), it transparently forwards the request to the API Host we have set on the current environment (localhost:2368). For all intents and purposes, to an API consumer it is just as if we are requesting the Ghost API directly.

In reality, the Prism API Proxy is doing a bunch of processing on the traffic passing through it. It logs the traffic to the API Designer for easy debugging. In addition, when the API Discovery setting is toggled on in the environment, it uses this HTTP traffic to automatically build endpoint definitions. That’s right, it inspects the query string, headers, request body, and response body, to automatically build JSON Schemas, examples, and more for your endpoints. It even makes best guesses at dynamic path params in your URL!

Do It Yourself

API Discovery works locally with the OS X app version of the API designer, and also works with the web version of the API designer + hosted Prism.

There is an interactive academy tutorial in the designer, but if you really must read, here’s how to get it working, step by step:

1. In the designer, create a workspace -> project -> environment.
2. Set the API Host in the environment settings, and make sure that an API is actually running at that location! The host should include the protocol, so something like “http://localhost:3000", not “localhost:3000”.
3. Toggle the API Discovery option to “On” in the environment proxy settings tab.
4. Save the environment by clicking “Save” at the top of the screen.
5. Select “Local Proxy” in the proxy bar dropdown (bottom left of the screen), and make sure that it is toggled to on and running (or simply select the hosted proxy if you are using a publicly available API host).
6. Load one of your endpoints through the proxy. You can do this in your browser for GET requests, or by sending requests via the API Designer, curl, etc. For example, if you have a “GET /todos” endpoint, and the proxy is running on http://localhost:4010, visit http://localhost:4010/todos in your browser. After a moment, you will see the new endpoint in your endpoints list in the API Designer!
7. Repeat step 6 for the rest of your endpoints.
8. Smile.

We are incredibly excited about this feature, and would love your feedback. Try it out, and let us know what you think!

In Part II, we will explore how to use this API Discovery functionality in other ways. For example, transparently to discovery private APIs that you don’t have access to, and leveraging pre-existing test suites to generate traffic / discovery.

Head on over to https://stoplight.io to get started.

Happy Designing!
The StopLight Team
Marc, Rana, Tom, and Vazha