Importing OpenAPI specs into APISIX routes: when teams need it
Teams need OpenAPI import when they already maintain OpenAPI 3 documents and want those documents to drive gateway routes, rather than keeping a second set of hand-written route definitions that drifts from the API contract. The ADC command convert openapi (from the API7 ADC project, Apache-2.0) reads an OpenAPI document and produces APISIX route configuration from it, so the spec becomes the starting point for routing. A separate, complementary step is the oas-validator plugin, which checks live requests against the same OpenAPI document at the gateway. Together they let one document shape both what the gateway forwards and what it accepts, although each still needs its own review.
The conversion is a starting point, not a finished gateway configuration. Expect the generated routes to cover paths, methods and the upstream mapping you supply, while authentication, rate limits, transformations and other traffic policies are added afterwards as plugins and upstreams. Confirm with the ADC repository exactly which OpenAPI constructs convert and how each is represented in the output before you rely on the import for a large or complex specification. Ask your team to check the generated routes against a small set of real endpoints in a non-production environment first.
The oas-validator plugin fits teams that want the gateway to reject malformed requests before they reach the upstream. It validates request method, path, query parameters, headers and body against an OpenAPI 3.x document, supplied inline or by URL. Failures return 400 by default, or you can configure it to log only, which is useful during rollout to measure how many legitimate clients would be affected. For remote specs, the plugin caches the document for 3,600 seconds, so a spec change may take up to an hour to take effect unless you manage the cache differently. Confirm this behavior against the plugin documentation for your APISIX version. The approach fits when the OpenAPI document is accurate, versioned and owned by the API team, and when that team accepts that the spec is the contract the gateway enforces. It fits less well when specs are incomplete, lag behind the running service, or describe endpoints the team does not want exposed. In those cases, keep hand-managed routes, or fix the spec first. Decide early who approves changes to the document, because a spec edit can alter both generated routes and validation behavior at once.
What maps automatically from an OpenAPI document and what does not
The path and method pairs in an OpenAPI 3 document are the part that converts most predictably. Each path template becomes a candidate route URI, each operation's HTTP method becomes the route's method match, and path parameters such as {orderId} carry over as APISIX path variables. The servers block is the input most often misread: its URL is a base path for the generated route or a hint for the upstream, depending on the conversion settings, so check whether a server URL with a path prefix ends up duplicated in the route. The operationId is useful for naming and for tracing a route back to its source operation, but do not assume it becomes a stable route identifier across regenerations. Confirm each of these mappings against the ADC version you run and the target APISIX version, because the output shape of convert openapi changes between releases.
Most of what protects and shapes traffic does not come from the specification. Authentication schemes declared under components.securitySchemes may be recorded in the document, but the gateway enforcement still has to be configured as plugins such as openid-connect or key-auth, and rate limits, timeouts, upstream health checks and request transformations have no OpenAPI counterpart that the converter will create for you. Upstream node addresses also need an explicit decision, since the server URL in the spec is rarely the production backend. Plan these as a separate, reviewed layer on top of the generated routes, and keep them in the same version-controlled files so that a regenerated route does not silently drop them.
Run convert openapi on a small, representative sample spec before touching the full API catalog. Include an operation with path parameters, one with a security requirement, one with a non-default server URL and one with a request body, then diff the output against what you expected and against the live APISIX configuration. Record which elements were dropped or altered, because that list becomes your acceptance checklist for the import. Treat the converter output as a draft that a person reviews, not as a finished configuration.
Options for generating and validating routes from OpenAPI
This table compares four ways to keep APISIX routes aligned with an OpenAPI 3 document: one-time conversion, Git-managed regeneration, and request validation inline or by URL. Read each row against your team's review capacity and how often the spec changes. The main takeaway is that the cheaper option at the start usually carries the higher drift risk later.
| Option | When it fits | Main trade-off | Watch for |
|---|---|---|---|
| Convert once, then hand-edit in APISIX | A small, stable API with few plugins and a single owner of the gateway config | Spec and gateway diverge as soon as either side changes | Manual edits made in the Admin API that nobody copies back to the spec |
| Keep converted output in Git and regenerate with ADC | Several teams change the spec or plugins and you want review on every change | Needs a pipeline step, a review habit and a place to store plugin settings the spec cannot express | Regeneration overwriting hand-added plugins or upstreams if they are not kept separately |
| Validate requests with oas-validator inline | The spec is versioned with the gateway config and must be enforced at the edge | Spec text is stored in the route config, so updates must go through the same change process | Large specs making route configuration harder to review |
| Validate requests with oas-validator by URL | The spec is published by a separate team or service and should be the single source | Gateway depends on that URL, and remote specs are cached for 3,600 seconds (oas-validator docs), so changes take up to an hour to apply | Unreachable spec endpoints and cache timing during incident response |
| Reject mode (default) | Production APIs where malformed requests must never reach the upstream | Clients receive 400 responses for any mismatch, including spec errors you have not fixed yet | Breaking clients after a spec change that was not tested first |
| Log-only mode | Rollout of a new spec or an audit of how real traffic differs from the document | Invalid requests still reach the upstream, so it is not a control | Logs that fill up without anyone reviewing them or switching back to reject |
Setting up the import pipeline step by step
This sequence takes one OpenAPI 3 document from a file in Git to a reviewed, validated set of APISIX routes that can be synced safely. Each step ends with a check you can run before moving on.
Install ADC and confirm the Admin API connection
Your platform or gateway engineer installs ADC, the API Declarative CLI published by API7 under the Apache-2.0 license, on a workstation or CI runner. Point it at the APISIX Admin API in the environment you are targeting, using an admin key supplied through the process environment rather than a file in the repository. Run the ping command against that environment. The step is done when ping reports a successful connection to the Admin API. If it fails, confirm the Admin API address and that the runner can reach it, since traditional mode serves the Admin API on port 9180 by default.
Lint and convert the sample OpenAPI document
Start with one representative OpenAPI 3 document, ideally a small service rather than your full API estate. Run the lint command to catch structural problems in the document, then run convert openapi to produce an ADC configuration file from it. Keep the generated file in a branch so it can be reviewed like any other code change. The step is done when lint passes and the conversion completes without errors. Record any warnings, because they usually point to schema features the conversion does not map and that you will need to handle by hand.
Review the generated routes line by line
The reviewing engineer compares the generated routes with the source document. Check that each path and HTTP method appears once, that path parameters are carried over, and that the upstream host and port are placeholders you will replace later rather than values copied by accident. Confirm the route names and any tags make sense to the teams who will read them. Note which parts of the spec, such as security schemes, servers or response definitions, did not map automatically. The step is done when the reviewer can explain every generated route and has signed off the difference between the document and the output.
Add plugins and upstreams in a separate layer
Keep gateway policy out of the generated file. Create a second configuration layer that holds the real upstream addresses for each environment, authentication plugins such as key-auth, jwt-auth or openid-connect, and rate limits or other traffic policies. Merge or reference this layer so that regenerating routes from the spec never overwrites it. The step is done when a dry run of the combined configuration shows the expected upstream nodes and plugin settings on the right routes, and no route is left with a placeholder address.
Configure oas-validator with the same spec
Enable the oas-validator plugin on the routes or service that the spec describes, pointing it at the same OpenAPI 3.x document you converted. Decide whether the document is supplied inline or by URL. If you use a URL, note that the plugin caches remote specs for 3,600 seconds, so a spec change will not take effect immediately. Set the failure behavior deliberately: the default rejects failing requests with 400, while logging only is useful during a rollout. The step is done when a deliberately malformed request in a test environment is rejected or logged as configured, and a valid request passes.
Run diff and ping before sync
Run the diff command against the target environment to compare the desired configuration with what the Admin API currently holds. Read the diff as a change list, looking for removed routes, changed upstreams and any plugin settings that will be overwritten. Then run ping again to confirm the connection is still valid for the sync. Only after an approver has reviewed the diff should the sync command run. The step is done when the diff contains only the changes you expected, and a record of that review is stored with the change, so the sync is traceable.
Keeping the OpenAPI spec and gateway routes in sync
Three artifacts describe the same API once the import is done: the OpenAPI document, the routes generated from it, and any change an operator makes directly in the gateway. Drift starts when these diverge. A developer adds an endpoint to the spec but nobody regenerates the routes, or an engineer edits a route in the Admin API during an incident and never copies the change back. Either way, the spec the validator checks against no longer matches what the gateway forwards. The safe rule is that the spec and the Git repository are the sources of truth, and the live gateway is only ever a output of them. Confirm whether your team also allows direct Admin API edits, and if so, how those edits are detected and reconciled.
The fix is a Git-based workflow where ADC runs in CI. A pipeline can run adc convert openapi on the spec, then adc lint and adc diff against the running gateway, and only run adc sync after a reviewer approves the diff. A diff in a pull request shows exactly which routes will change before they reach production, which is the cheapest place to catch a surprise. Keep the generated file and the hand-written additions in separate files, so regeneration writes only the generated part. Plugins such as authentication, rate limits and the oas-validator configuration belong in the hand-written layer, and you must test that a regeneration run leaves them intact. Confirm in the ADC version you choose how it handles resources it did not create, and whether a sync removes gateway objects that are absent from its input. That behavior decides whether your layering holds.
Security considerations when routes come from a spec
A generated route is only as safe as the pipeline that creates it. The cards below cover the credentials, validation limits, remote inputs, public exposure, review and audit trail that connect the spec to the live gateway.
Admin API credentials in CI
ADC writes routes through the APISIX Admin API, so the pipeline that runs convert and sync holds a credential that can change every route. Store the Admin key in the CI secret store, scope the runner so only the sync job can read it, and keep the key out of logs and generated files. Check whether your team can use a separate, narrower credential for dry runs and lint jobs that never write. Confirm the exact Admin API key handling with the APISIX and ADC documentation for your version.
Validation is not authorization
The oas-validator plugin checks that a request matches the spec's method, path, parameters, headers and body. It confirms shape, not identity or permission, so a well-formed request from an unauthorized caller still passes. Pair the validator with authentication and access restriction plugins on the same route. Test both a valid request with the wrong credentials and an invalid request with the right ones.
Remote spec URLs and their cache
When the validator loads a spec by URL, the gateway depends on that URL and on the content it returns. Fetch remote specs only from hosts your change process controls, and pin a version where possible. Remote specs are cached for a fixed period, so a changed document may not take effect immediately. Confirm the cache duration and refresh behavior for your APISIX version before relying on it for a security rule.
Public exposure of the spec
A published OpenAPI document lists every path, parameter and schema, which helps attackers map an API before they test it. Decide which specs are public developer documentation and which are internal, and serve internal ones only behind authentication. Remove internal paths, example values and server addresses from any copy that leaves your network. Review the published copy whenever the source spec changes.
Review gates for generated routes
Generated routes can expose a new path or drop a plugin without anyone noticing in the diff of a large YAML file. Require a reviewer from the API owner and the security team for changes that add paths, alter authentication or change upstreams. Run adc diff and adc lint in the merge request so the reviewer sees the live effect. Treat a route with no authentication plugin as a blocking finding unless it is documented as public.
Audit trail for spec changes
Your audit evidence should show who changed the spec, who approved it and what reached the gateway. Keep the spec in Git with signed or protected commits, and link each sync run to its commit and pipeline record. Retain the pipeline logs and the dump output taken before each sync so a rollback target exists. Ask your auditors which retention period they expect for these records, because the period comes from your policy, not from APISIX.
Questions teams ask before importing OpenAPI specs
What does an OpenAPI import into APISIX cost, and what drives the effort?
The cost is the engineering time to convert your specs, review the generated routes, add plugins and upstreams, wire validation, and set up CI. Most of that effort depends on the input: how complete and consistent your OpenAPI 3 documents are, how many APIs and operations you publish, how many plugin layers (authentication, rate limits, transformations) each route needs, and whether a CI pipeline must sync changes on every merge. A fixed-scope quote should list the spec count, the environments, the plugin set and the CI deliverables in writing. Ask for one-time versus recurring items, such as ongoing spec sync and upgrades, so you can compare the first build against the run cost.
How long does a pilot import take, and what sets the duration?
Duration depends on how many APIs are in the pilot, how clean their specs are, and how many plugins and upstream rules must be attached after conversion. A narrow pilot with one or two well-formed specs and a single environment moves faster than a multi-team rollout with authentication, validation and CI sync. Ask the provider to state the timeline in the written scope, with the milestones for spec review, conversion, plugin work, testing in a non-production environment and handover. Any duration not backed by your own spec inventory should be treated as an estimate to challenge.
What does the work need from our team?
You need named spec owners who can answer questions about intended behavior, because the gateway can only enforce what the document describes. You also need Admin API access to a non-production APISIX instance, plus a decision on how credentials are issued and stored. Confirm which environments exist (development, staging, production), who approves promotion between them, and where the OpenAPI files live today. Ask whether your team must provide a Git repository, CI runners and a secrets store for the ADC configuration. Write these dependencies into the scope so that delays on your side are visible and do not become disputes.
Can an internal team import OpenAPI specs into APISIX alone?
Yes, an experienced platform or API team can do it alone, provided it has someone comfortable with APISIX routes and plugins, the ADC command-line tool, and the Admin API. ADC is open source under Apache-2.0 and includes a convert openapi command, so the first conversion is accessible. The harder work is judgment: deciding which spec fields become plugin configuration, how the oas-validator plugin should behave on failures, and how to keep the gateway and the spec aligned over time. If that skill is missing today, a partner can handle the first build and hand over the runbooks, or your team can take the work over in stages.
How does importing OpenAPI specs relate to migrating from another gateway?
An OpenAPI import creates routes from specs you already maintain, which is useful when APIs are documented but their gateway configuration lives in another product. A gateway migration moves routes, authentication and traffic policies from the current gateway, and it usually needs parallel running and a rollback path. The two often overlap: the spec describes the contract, while the migration inventory describes the live behavior that clients depend on. Compare generated routes against the current gateway's configuration before cutover, and treat any policy that exists only in the old gateway as a separate work item. If you plan a migration, scope the import as one step inside it.
How do we keep the OpenAPI spec and the gateway routes in sync?
Keep the OpenAPI document in version control as the source for the API contract, regenerate routes from it in CI, and use ADC diff and lint before any sync. ADC's diff shows what would change in APISIX, and sync applies it, so a pull request can display the route changes a spec edit would cause. Decide who approves spec changes, and whether a spec that fails lint blocks the merge. Pair this with validation at runtime: the oas-validator plugin can reject non-conforming requests with a 400 response by default, or log only during a trial period, and it can load remote specs with a cache of 3,600 seconds.
Does the OpenAPI import handle security and compliance requirements?
The import itself creates routes, but it does not decide your security controls. Authentication, rate limits, TLS and request validation must be added and tested after conversion, and that work should follow your own control requirements. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications; independent auditors do that. Ask the provider to show which validation and access controls are applied to each route, how changes are logged, and where configuration evidence is stored.
How DeployOpen scopes and delivers OpenAPI-driven routes
DeployOpen starts with a written scope before any conversion runs. The scope names the OpenAPI documents in play, the target APISIX environments, the gateway deployment mode, and which routes will be generated automatically versus hand-built. It also records the plugins to attach after import, the upstream services each route points to, and the validation behavior expected for each API, whether that is rejecting failed requests or only logging them. Deliverables and acceptance checks are agreed in the same document, so the client knows what a finished import looks like before work begins. The quote follows from that scope, so ask for it to list each specification and each environment separately.
Before building, DeployOpen reviews the client's specifications for the problems that break conversion. Engineers check that each document is OpenAPI 3.x, that servers URLs match the intended upstreams, that operation IDs and tags are consistent, and that security schemes are declared in a form the gateway can map to authentication plugins. Remote specs are reviewed for where they are hosted and who controls changes, because the oas-validator plugin can load them by URL and caches them for 3,600 seconds. The import pipeline then runs inside the client's own infrastructure: ADC conversion, linting and diffing in the client's CI system, with the Admin API target and credentials held in the client's secret store. The pipeline is documented with the decisions made, the commands used and the rollback steps.
After delivery, the work can move to a retainer. Retainers cover specification changes, plugin version updates, periodic ADC and APISIX upgrades, and reviews of drift between the spec repository and the live gateway. Confirm during scoping who approves changes to a specification, how breaking API changes reach the gateway team, and whether validation is enforced or logged in production. Those answers decide how much ongoing effort the pipeline needs and whether a retainer or an internal team should own it.
