OpenAPI REST Client

Lightweight, free and OpenAPI-driven request collection generator. Keep your API collections always in sync with your openapi.json, without limits or paid tiers.

Motivation

When working on backend projects with multiple services and containers, it is common to have a dedicated service to expose API documentation through OpenAPI / Swagger.

However, interacting with those APIs during development usually depends on external tools such as Postman or Insomnia, which often introduce friction:

• Manual collection maintenance.
• Sync issues with evolving APIs.
• Paywalls or usage limits.
• Vendor lock-in.

This project was born from a simple need: having a fully free, self-contained and automated way to generate and maintain API request collections directly from OpenAPI definitions.

What This Project Is

OpenApiReqCli is a lightweight tool designed to live alongside your backend services.

Think of it as another container in your stack:

• You have your API.
• You have your OpenAPI documentation.
• And now you have an always up-to-date request collection.

How It Works

The core idea is simple:

• The source of truth is your openapi.json.
• The app parses it.
• It generates a request collection with a Postman-like workflow.
• It keeps the collection in sync whenever the OpenAPI spec changes.

No manual edits. No drift.

Screenshots

Intended Usage

This tool is meant to be integrated per project, not globally.

Typical setup:

• Backend service(s).
• OpenAPI documentation service.
• OpenApiReqCli container/service.

This ensures each project owns:

• Its API contract (openapi.json).
• Its request collection, generated from it.

Why This Exists

Most existing tools in this space:

• Are SaaS-based.
• Require accounts.
• Limit updates or requests.
• Lock useful features behind paywalls.

This project aims to be:

• Free, actually free.
• Self-hosted.
• OpenAPI-first.
• Zero vendor dependency.

Philosophy

• Your API contract is your single source of truth.
• Your tooling should adapt to it, not the other way around.
• You should not have to pay to keep your own API collections updated.

License

This project is copyleft software licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.

Installation

pnpm install

Development

pnpm dev

Open the URL printed by Vite, usually http://localhost:5173.

Git Hooks

This repository includes a tracked pre-commit hook that blocks commits unless the package.json version is greater than the version in HEAD.

Install the hook once per clone:

pnpm hooks:install

Docker

See Docker Image Guide for build, versioning, publishing, running, and update instructions.

Import Or Update openapi.json

1. Click Import / Update OpenAPI.
2. Select a valid OpenAPI .json file.
3. The app validates the document with @apidevtools/swagger-parser.
4. Endpoints appear in the right panel grouped by tags or by the first path segment.

Each endpoint uses a stable id in the METHOD path format, for example GET /health or POST /auth/login.

OpenAPI + Local Overrides Model

The OpenAPI collection is the source of truth. When importing again:

• Existing endpoints update their definition from OpenAPI.
• New endpoints are added.
• Endpoints that no longer exist are kept and marked as removed.
• User edits are preserved as local overrides by endpointId.

The app persists with localforage:

• Basic spec metadata.
• Generated endpoints.
• Endpoint overrides.
• Open tabs.
• Active endpoint.
• baseUrl, global auth, and local variables.

Included MVP

• Params, headers, body, auth, and script editors.
• Default JSON body generated from requestBody.schema when possible.
• Multipart form/file request support when OpenAPI defines multipart/form-data or binary fields.
• Native fetch request execution.
• Response status, duration, headers, body, and image preview for image/* responses.
• Local persistence of user edits.
• Browser-only CORS/network error hints.

Pre-request and post-request script editors persist their content. Post-request scripts can store local variables with the simple store API.

Saving tokens from a response and reusing them

If an auth endpoint returns a token like access_token, you can save it in the endpoint's Post-request Script:

store.set('access_token', responseJson.access_token)
store.set('refresh_token', responseJson.refresh_token)

Saved variables can be reused anywhere request interpolation is supported, including auth, headers, params, and body fields, with double curly braces:

{{access_token}}

Typical flow:

1. Send /auth/login or /auth/register.
2. In that endpoint's Post-request Script, save the token with store.set('access_token', responseJson.access_token).
3. Open a protected endpoint such as /users/me.
4. In Authorization, choose Bearer Token.
5. Set Endpoint bearer token to {{access_token}}.

Notes:

• Use store.get('access_token') to read a saved value inside scripts.
• Use store.remove('access_token') to delete a saved value.
• The {{variable_name}} syntax is only for request fields. Inside scripts, use store.set(...) / store.get(...).