README
¶
Change an API spec without breaking it.
openapi-edit provides safe structural edits to an
OpenAPI 3.x specification — the kind of
change where touching one place obliges you to touch several others, and forgetting
one leaves a document that no longer resolves.
Status: early. The scope below is settled and operations arrive one at a time, as each earns its place.
RenameSchemaandRedirectSchemaare the first.
Introduction
Renaming a schema is the canonical example. The rename itself is a single map
operation, but every $ref that pointed at the old name is now dangling — and those
$refs can be anywhere: nested inside another schema's properties, inside an
allOf branch, in a response's content, in a parameter, in a callback. Getting this
right means walking the entire document. Getting it wrong means a spec that looks
fine and fails to resolve.
That traversal is worth writing once, carefully, and reusing.
This module serves two kinds of caller:
- Directly, when you are writing code against your own specification and want to make a specific change safely, without reimplementing the bookkeeping.
- As a dependency, for tools like
openapi-compressandopenapi-flattenthat run an algorithm over a whole specification and need the same primitives underneath.
Usage
go get github.com/MarkRosemaker/openapi-edit
import (
"github.com/MarkRosemaker/openapi"
edit "github.com/MarkRosemaker/openapi-edit"
)
// Renames the schema and rewrites every reference to it.
if err := edit.RenameSchema(doc, "GetV1PetByPetIDOkJSONResponse", "Pet"); err != nil {
log.Fatal(err)
}
The schema keeps its position among the components, so a rename produces a one-line change rather than reordering the section.
Renaming a schema to its current name does nothing and reports no error. Otherwise the rename fails, changing nothing at all, in three cases:
| Error | When |
|---|---|
ErrSchemaNotFound |
components.schemas has no schema under the old name |
ErrSchemaExists |
the new name is already taken by another schema |
ErrInvalidSchemaName |
the new name is not a valid key under components |
The second is the interesting one. Renaming onto an existing schema would silently discard one of two different definitions and repoint every reference at whichever survived — a change that looks successful and quietly alters the API.
The third matters more than validity alone suggests: a name containing / would
produce a reference that resolves somewhere else entirely, and one containing a
space would produce a reference that does not resolve at all. Component keys must
match ^[a-zA-Z0-9.\-_]+$.
Redirecting a schema onto another
RenameSchema refuses to rename a schema onto a name that already exists
(ErrSchemaExists). RedirectSchema is for when that's exactly the point —
several near-duplicate schemas, typically ones an OpenAPI generator produced
one per endpoint that happen to describe the same thing, are being
consolidated onto one of them:
// Repoints every reference to "GetPetOkResponse" at "Pet", then removes
// "GetPetOkResponse" from components.schemas.
if err := edit.RedirectSchema(doc, "GetPetOkResponse", "Pet", ""); err != nil {
log.Fatal(err)
}
What it actually does, precisely — this is a rewrite of references, not a combination of content:
- It finds every
$refin the document whose value is"#/components/schemas/GetPetOkResponse"(via the same [walkSchemaRefs] traversalRenameSchemauses) and rewrites each one to"#/components/schemas/Pet". - It deletes the
"GetPetOkResponse"entry fromcomponents.schemas. - It does not look at, merge, or otherwise change the content of either
schema.
Pet's definition (its properties, its bounds, its wording) is whatever it already was, byte for byte;GetPetOkResponse's definition is simply gone, not folded intoPet's.
If GetPetOkResponse carried bounds or wording worth keeping, pass it as
description instead of an empty string: it becomes the $ref-level
description on every reference this repoints, replacing whatever
description that reference already had. That's the one piece of
GetPetOkResponse this function can carry forward — everything else about
its definition is discarded the moment step 2 above runs, so this is the
last chance to keep any of it on the sites that used it.
Redirecting a schema onto itself does nothing and reports no error.
Otherwise it fails, changing nothing at all, if either name is not in
components.schemas (ErrSchemaNotFound).
This is deliberately not the same operation as combining two schemas into
one wider shape (adding one's properties, enum values, etc. to the other) —
that's openapi-merge's job, and it works on two schema values directly
rather than on a document and its references. The two are meant to compose
at the call site rather than one wrapping the other: a caller deduplicating
a specification decides, using whatever means it likes (openapi-merge
included), which of two schemas should survive and what its content should
be, then calls RedirectSchema to point every reference at the survivor and
drop the one that lost. See Scope below.
Scope
Operations belong here when they satisfy two conditions: they mutate a document, and doing them correctly requires knowledge of the document beyond the node being changed.
In scope
- ✅ Renaming a component and rewriting every reference to it (
RenameSchema) - ✅ Repointing every reference to a duplicate component onto the one that
survives, and removing the duplicate (
RedirectSchema) - Moving a definition between inline and
components, keeping references intact
Out of scope
- Deciding whether two things should be merged — that is
openapi-compare - Combining two independently inferred schemas into one wider schema that
covers what both described — that is
openapi-merge.RedirectSchemaabove is a different, narrower operation: it never reads or changes either schema's own definition, only the references that pointed at the one being discarded. - Whole-document policies such as flattening or deduplication — those are their own modules, and they are expected to use this one
- Anything universal enough to belong on the types themselves — that goes into
openapiinstead, so that users who only want to parse and validate a spec aren't made to carry it
The openapi family
| Module | Purpose |
|---|---|
| openapi | Parse, validate, and write OpenAPI 3.x specifications |
| openapi-compare | Compare specification objects — exact equality and shape equivalence |
| openapi-edit (this module) | Safe structural edits, such as renaming a schema and rewriting every $ref to it |
| openapi-flatten | Promote inline definitions into named components entries |
| openapi-compress | Deduplicate and merge equivalent component schemas |
| openapi-merge | Merge schemas that were inferred independently from different samples |
| openapi-enrich | Infer specification content from observed HTTP traffic |
| openapi-codegen | Generate Go types, clients, and servers from a specification |
Contributing
If you have any contributions to make, please submit a pull request or open an issue on the GitHub repository.
License
This project is licensed under the Apache 2.0 License.
Documentation
¶
Overview ¶
Package edit provides structural edits to an OpenAPI document — changes where touching one place obliges you to touch several others.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RedirectSchema ¶
RedirectSchema repoints every reference to oldName at newName and removes oldName from components.schemas. It does not read or change either schema's own definition — newName's shape is left exactly as it was, and oldName's is discarded along with oldName itself, not merged into newName's. Combining two schemas' definitions into one wider shape is a distinct, unrelated operation; see openapi-merge for that.
It differs from RenameSchema, which refuses to rename a schema onto a name that already exists (ErrSchemaExists): redirecting onto an existing schema is exactly the point here, typically because several near-duplicate schemas (e.g. ones an OpenAPI generator produced one per endpoint, that happen to describe the same thing) are being consolidated onto one of them.
If description is non-empty, it becomes the $ref-level description on every reference this repoints, replacing whatever description that reference already had. The usual reason to set it is that oldName's own definition — its bounds, its wording — is about to be discarded once oldName is gone; setting description is how that information survives on the references that used it, rather than being lost along with oldName.
It fails, changing nothing, if oldName or newName is not in components.schemas (ErrSchemaNotFound).
func RenameSchema ¶
RenameSchema renames a schema in components.schemas and rewrites every reference to it, wherever in the document that reference occurs.
The schema keeps its position among the components, so renaming produces a one-line change rather than reordering the section.
Renaming a schema to its current name does nothing and reports no error. Otherwise it fails, changing nothing, if:
- oldName is not in components.schemas (ErrSchemaNotFound);
- newName is already taken (ErrSchemaExists) — renaming onto an existing schema would silently discard one of two different definitions, and point every reference to whichever survived;
- newName could not be referenced (ErrInvalidSchemaName).
Types ¶
type ErrInvalidSchemaName ¶
type ErrInvalidSchemaName struct{ Name string }
ErrInvalidSchemaName is returned when the new name is not a valid key under components, and so could not be referenced.
func (*ErrInvalidSchemaName) Error ¶
func (e *ErrInvalidSchemaName) Error() string
type ErrSchemaExists ¶
type ErrSchemaExists struct{ Name string }
ErrSchemaExists is returned when the new name is already taken by another schema. Renaming onto it would silently merge two definitions into one.
func (*ErrSchemaExists) Error ¶
func (e *ErrSchemaExists) Error() string
type ErrSchemaNotFound ¶
type ErrSchemaNotFound struct{ Name string }
ErrSchemaNotFound is returned when the schema to rename is not in components.schemas.
func (*ErrSchemaNotFound) Error ¶
func (e *ErrSchemaNotFound) Error() string
Source Files