Guides
Turn traffic into API docs
Capture an API's traffic, build an endpoint catalog in Insights, export OpenAPI, import it into the API client, and generate HTML documentation.
An undocumented API is easier to describe once you’ve watched it run. This guide captures an API’s traffic, lets Insights group it into an endpoint catalog, exports an OpenAPI document, imports it into the API client as a collection and editable spec, and generates HTML documentation from it.
What you need
Section titled “What you need”| Cloak Proxy capturing the API, with HTTPS decrypted | The catalog and OpenAPI export read decrypted requests |
| A thorough session covering the endpoints you want documented | Each endpoint needs at least one captured call |
Capture the API
Section titled “Capture the API”-
Turn on capture and decrypt the API’s host (see SSL Proxying).
-
Exercise each endpoint at least once, with realistic parameters. Hit the same endpoint with different IDs so Cloak Proxy can tell the variable part of the path from the fixed part.
Build the endpoint catalog
Section titled “Build the endpoint catalog”Open Insights (<kbd>⌥</kbd> <kbd>⌘</kbd> <kbd>I</kbd>) and select the Endpoints tab. Cloak Proxy groups the traffic into endpoint templates, so /users/1 and /users/2 become one /users/{id}.
The API catalog: endpoints with calls, error rate, latency and size.
- Filter endpoints
- Export OpenAPI
- Templated paths like /v1/reviews/{id}
- Calls, errors, p50/p95, avg size
-
Read the table: method, host, path template, call count, error rate, p50/p95 and average response size. IDs, UUIDs, hashes and dates in paths are collapsed into
{id},{uuid}, and so on. -
Select an endpoint to see its status codes, query parameters, content types and callers — the raw material for documentation.
Export OpenAPI
Section titled “Export OpenAPI”-
Click Export OpenAPI… on the Endpoints tab to export every catalogued endpoint, or export a selection of requests with Export Request → OpenAPI (YAML)… from the traffic list’s right-click menu.
-
The export templates paths, infers request and response schemas from the captured JSON, lists query and path parameters with examples, and records the servers it saw. Save the
.yamlfile.
Import it into the API client and refine
Section titled “Import it into the API client and refine”-
In the API Client (
<kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>O</kbd>), click Import, choose Choose Files…, and pick the exported YAML (or paste it).Import the OpenAPI file as a collection and a linked spec.
- Choose Files, or paste below
- Import
Importing an OpenAPI document creates a collection (requests with example bodies) and adds the document to Specs.
-
Open the Specs view to edit the document. The linter flags missing descriptions, security and schemas, so you can see what to fill in.
The Specs editor with live linting and Sync Collection.
- Specs section
- Sync Collection keeps the collection in step
- Preview Docs
- Lint problems to fix
-
Add summaries, descriptions, security and missing schemas in the editor. Click Sync Collection to update the linked collection from the spec (your tests, scripts, auth and examples are kept). See Specs.
Generate documentation
Section titled “Generate documentation”-
From the Specs editor, click Preview Docs to render the documentation in your browser.
-
To save a shareable file, open the collection and choose Export API Documentation (HTML)… from its More menu, or generate it from the command line:
Terminal cloakctl docs Petstore --out docs.htmlThe HTML is a single self-contained file with code samples and the collection’s branding.
Clean up
Section titled “Clean up”-
Turn off capture and SSL Proxying for the API if you only needed the documentation pass.
-
Commit the collection and spec to Git if you want to keep them (the workspace is a folder of JSON files). See Workspace and Git.