apache / apache/apisix

feat: better support for OpenAPI spec

Open
#9,276 0 comments 6 reactions 0 assignees View on GitHub
discuss enhancement
Dominant language
Lua
Stars
17.1k
Forks
2.9k
Avg merge
3d 16h
Merged PRs (30d)
63

Description

### Description

API gateways are increasingly being used for complete API lifecycle management. A core part of this aspect is the support for specifications like the OpenAPI spec to standardize, decouple, and integrate different steps in the API lifecycle.

One use case here is to use APISIX for mocking the API:

> The company has front-end and back-end developers. With the help of the business, they agree on an OpenAPI spec. Then, they go on developing their part. As a frontend developer, I want to be able to develop independently from the backend part. For this reason, a couple of mock servers have popped up: you feed them with the OpenAPI spec, and they serve the data in the example section of the spec.

APISIX [currently supports the OpenAPI spec](https://apisix.apache.org/docs/dashboard/IMPORT_OPENAPI_USER_GUIDE/) to some extent, but you would need additional extensions, and there is no change management.

APISIX also has a [mocking Plugin](https://apisix.apache.org/docs/apisix/plugins/mocking/), but it is unrelated to the OpenAPI spec, and you have to mock requests manually.

To support this new case, APISIX needs to add the following features:

- More extensive support for the OpenAPI spec
- Serve mock requests based on the examples section in the spec
- Replace examples with real Upstream
- Dynamically mirror changes to APISIX from the spec file

This issue thread can be a place to discuss the need for such features and how they should be implemented.

Based on the [discussion](https://lists.apache.org/thread/jvc2p1poj4bvl8r3pdk890djjnb51jtp) started by @nfrankel in dev@apisix.apache.org.

Contributor guide

Open the contributing guide

Research direction

Start with the linked OpenAPI import guide and mocking plugin documentation, then review the linked mailing-list discussion for the proposed scope. Done would require an agreed implementation for broader OpenAPI support, example-based mock serving, replacement with real upstreams, and dynamic synchronization; the issue currently presents these as discussion topics rather than a defined change.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.