"Feed it JSON. Loot OpenAPI."
OpenAPI Example Generator is a self-contained Django application that helps developers create valid OpenAPI 3.1 documentation from request and response examples. Rather than requiring developers to write an OpenAPI YAML document manually, the application allows them to describe an API operation through a guided interface and automatically converts that information into a validated specification.
The application does not connect to or execute requests against live APIs. Developers provide the relevant information directly, keeping the initial product safe, predictable, and focused on documentation generation.
OpenAPI documentation is valuable for communicating API behavior, generating interactive documentation, creating client libraries, and validating integrations. However, manually writing OpenAPI YAML can be tedious and unfamiliar, particularly when documenting an existing API.
This application reduces that work by allowing developers to provide information in the form they already understand: HTTP methods, routes, headers, JSON request bodies, and expected JSON responses.
The application is intended for developers who:
- Have an existing or planned JSON API.
- Understand how an API operation should behave.
- Have example requests and responses available.
- Want to produce OpenAPI documentation without writing YAML manually.
- Need to document a small API incrementally rather than all at once.
An anonymous user can generate documentation for one API operation. An operation is defined as one HTTP method applied to one route, such as POST /customers or GET /customers/{customer_id}.
The user provides:
- The HTTP method.
- The route path.
- A summary and optional description.
- Path and query parameters.
- Required request headers or authentication method.
- An optional JSON request body.
- One or more expected responses.
- The status code, description, content type, and optional JSON body for each response.
The application parses the submitted examples and infers OpenAPI-compatible schemas, including object properties, arrays, primitive types, nullable values, and recognizable formats such as email addresses and date-time strings.
Before generating the final document, the application presents its inferences for review. The user can confirm or modify assumptions that cannot be established reliably from a single example, including whether fields are required, optional, or nullable.
The application then generates and validates an OpenAPI 3.1 YAML document for the operation. The user can preview, copy, or download the result without creating an account.
Anonymous submissions are not permanently saved.
A registered user can create and manage API projects. Each project stores general API information and any number of documented operations.
A project includes:
- API title.
- Version.
- Description.
- Base server URLs.
- Authentication schemes.
- Reusable schemas.
- Saved API operations.
Users can add, edit, duplicate, and remove operations. The application combines the approved operations into a complete OpenAPI 3.1 document that can be previewed, validated, and downloaded as YAML.
This allows developers to document an API incrementally while maintaining one consistent specification.
The application follows this process:
- Collect structured information about an API operation.
- Parse the provided request and response JSON.
- Infer schemas from the submitted examples.
- Identify assumptions that require developer confirmation.
- Convert the approved information into an OpenAPI operation.
- Add the operation to an OpenAPI document.
- Validate the completed document against OpenAPI 3.1.
- Present validation errors or allow the YAML to be downloaded.
The system must distinguish between observed values and approved contract rules. A submitted example demonstrates that a particular structure is possible, but it does not conclusively prove that every included property is required. The developer remains responsible for approving inferred requirements and constraints.
Each operation can contain multiple expected responses. For example, a POST /customers operation might include:
201— Customer created successfully.401— Authentication is required.409— Customer already exists.422— Request validation failed.
Each response can have its own description, content type, headers, example body, and inferred schema.
Expected error responses are treated as intentional parts of the API contract. They are not considered invalid merely because their status codes represent unsuccessful requests.
The application documents the structure of required headers but does not need real credentials.
Users should specify that an operation requires a bearer token or API key rather than submitting the credential itself. If the application detects likely secrets in fields such as Authorization, Cookie, or X-API-Key, it should warn the user and remove the sensitive value before processing or storage.
Actual authentication tokens must never appear in:
- Generated YAML.
- Saved project data.
- Application logs.
- Validation errors.
- Analytics or monitoring data.
Django will provide:
- User registration and authentication.
- Project and operation management.
- Form handling and validation.
- Database persistence.
- YAML previews and downloads.
The OpenAPI generation logic should be implemented as a framework-independent Python domain layer. Its primary responsibilities will include:
- Parsing JSON examples.
- Inferring JSON Schema-compatible structures.
- Merging information from multiple examples.
- Building OpenAPI operations.
- Assembling complete OpenAPI documents.
- Validating generated specifications.
- Serializing documents as YAML.
Separating this logic from Django will make the most important behavior easier to test, reuse, and reason about.
The MVP will support:
- OpenAPI 3.1.
- JSON request and response bodies.
- One anonymous operation at a time.
- Multiple expected responses per operation.
- Common HTTP methods.
- Path, query, and header parameters.
- Bearer-token and API-key authentication definitions.
- Type and format inference.
- Developer review of inferred schemas.
- Registered accounts.
- Saved API projects and operations.
- Complete project-level YAML generation.
- YAML preview, validation, copying, and download.
The initial version will not:
- Execute HTTP requests.
- Scan websites for endpoints.
- Store API credentials.
- Import
curlcommands, HAR files, or Postman collections. - Generate specifications by analyzing source code.
- Monitor live APIs for contract changes.
- Support XML or multipart request bodies.
- Guarantee that inferred schemas represent every possible API behavior.
- Automatically test an API implementation against the generated contract.
These capabilities may be considered after the central example-to-contract workflow is complete.
Build and thoroughly test the Python services that convert JSON examples into OpenAPI-compatible schemas, construct operations, assemble documents, and validate the result.
Create the guided interface for documenting one operation, reviewing inferred schemas, and downloading a validated YAML document.
Add registration, authentication, saved projects, operation management, and complete project-level document generation.
Improve schema merging, reusable component detection, credential redaction, error reporting, YAML previews, and overall usability.
The MVP is successful when a developer can describe an API operation through the interface, provide multiple expected JSON responses, review the inferred contract, and download a valid OpenAPI 3.1 YAML document without manually writing YAML.
A registered developer must also be able to save multiple operations within a project and export them as one complete, valid OpenAPI specification.