From a working interface to a readable API

When an application’s documentation is missing or incomplete, its interface gives you a practical starting point. Each search, page change or form submission exercises part of the underlying API. apispy turns those observations into a structured document, instead of leaving you to piece together individual network entries.

The result describes the operations you actually encountered. It is a starting point for understanding an integration, exploring a legacy application or reviewing the behavior of an API you maintain.

How to generate an OpenAPI document

  1. Open the analysis browser. Launch Chrome from apispy and navigate to the website. A dedicated persistent profile keeps the browser session available between captures.
  2. Exercise a workflow. Load a list, open a detail view, try filters and submit a form. Different inputs and responses give the inference engine more evidence.
  3. Select a domain. Open Operations to inspect the inferred request and response schemas. Use Coverage to find observations that need another look.
  4. Export the specification. In the Spec view, copy or export the generated OpenAPI JSON for that host.

What the document contains

apispy infers path templates, query parameters, request bodies and response schemas from captured traffic. Observed status codes and content types remain attached to their operations. Form submissions are documented under their own content type, including URL-encoded and multipart bodies.

Protocols such as GraphQL and JSON-RPC can place multiple operations behind one URL. apispy distinguishes these operations from the request body and gives each a synthetic documentation path. Extensions retain the real endpoint and transport information; the synthetic path is not a new URL to call.

Illustrative OpenAPI excerpt
{
  "openapi": "3.1.0",
  "paths": {
    "/items/{itemId}": {
      "get": {
        "responses": {
          "200": { "description": "Observed response" }
        }
      }
    }
  }
}

Improve the evidence before relying on it

A generated schema can only reflect what the browser observed. A field absent from every response will be absent from the document. An operation that returned only success responses tells you nothing about its error format.

Use the Coverage view to identify operations seen once, fields that were always null and statuses with no response body. Then return to the website and exercise the missing cases. Treat the output as observed behavior to review, not an authoritative contract or a complete server inventory.

Use the format that matches the traffic

OpenAPI describes HTTP operations. For the GraphQL type system, use apispy’s GraphQL schema reconstruction. For ongoing WebSocket or server-sent event conversations, export AsyncAPI documentation.

The OpenAPI 3.1 specification defines the output format. Review any captured example values before sharing the generated document.

Product behavior described here reflects apispy v0.1. Inferred documentation depends on the traffic you observe.