OpenAPI Overlay

An implementation of the OpenAPI Overlay Specification for applying modifications to OpenAPI documents

⚠️ This an alpha implementation. If you'd like to discuss a production use case please join the Speakeasy slack.

Features

• OpenAPI Overlay Specification Compliance: Full implementation of the OpenAPI Overlay Specification (2023-10-12)
• JSONPath Target Selection: Uses JSONPath expressions to select nodes for modification
• Remove and Update Actions: Support for both remove actions (pruning nodes) and update actions (merging values)
• Flexible Input/Output: Works with both YAML and JSON formats
• Batch Operations: Apply multiple modifications to large numbers of nodes in a single operation
• YAML v1.2 Support: Uses gopkg.in/yaml.v3 for YAML v1.2 parsing (superset of JSON)

About OpenAPI Overlays

This specification defines a means of editing an OpenAPI Specification file by applying a list of actions. Each action is either a remove action that prunes nodes or an update that merges a value into nodes. The nodes impacted are selected by a target expression which uses JSONPath.

The specification itself says very little about the input file to be modified or the output file. The presumed intention is that the input and output be an OpenAPI Specification, but that is not required.

In many ways, this is similar to JSONPatch, but without the requirement to use a single explicit path for each operation. This allows the creator of an overlay file to apply a single modification to a large number of nodes in the file within a single operation.

Apply an overlay to an OpenAPI document

Shows loading an overlay specification and applying it to transform an OpenAPI document.

overlayContent := `overlay: 1.0.0
info:
  title: Pet Store Enhancement Overlay
  version: 1.0.0
actions:
  - target: $.info.description
    update: Enhanced pet store API with additional features`

openAPIContent := `openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
  description: A simple pet store API
paths:
  /pets:
    get:
      summary: List pets
      responses:
        '200':
          description: A list of pets`

overlayFile := "temp_overlay.yaml"
openAPIFile := "temp_openapi.yaml"
if err := os.WriteFile(overlayFile, []byte(overlayContent), 0644); err != nil {
	panic(err)
}
if err := os.WriteFile(openAPIFile, []byte(openAPIContent), 0644); err != nil {
	panic(err)
}
defer os.Remove(overlayFile)
defer os.Remove(openAPIFile)

overlayDoc, err := overlay.Parse(overlayFile)
if err != nil {
	panic(err)
}

openAPINode, err := loader.LoadSpecification(openAPIFile)
if err != nil {
	panic(err)
}

err = overlayDoc.ApplyTo(openAPINode)
if err != nil {
	panic(err)
}

// Convert back to YAML string
var buf strings.Builder
encoder := yaml.NewEncoder(&buf)
encoder.SetIndent(2)
err = encoder.Encode(openAPINode)
if err != nil {
	panic(err)
}

fmt.Printf("Transformed document:\n%s", buf.String())

Create an overlay specification programmatically

Shows building an overlay specification with update and remove actions.

// Create update value as yaml.Node
var updateNode yaml.Node
updateNode.SetString("Enhanced API with additional features")

overlayDoc := &overlay.Overlay{
	Version: "1.0.0",
	Info: overlay.Info{
		Title:   "API Enhancement Overlay",
		Version: "1.0.0",
	},
	Actions: []overlay.Action{
		{
			Target: "$.info.description",
			Update: updateNode,
		},
		{
			Target: "$.paths['/deprecated-endpoint']",
			Remove: true,
		},
	},
}

result, err := overlayDoc.ToString()
if err != nil {
	panic(err)
}

fmt.Printf("Overlay specification:\n%s", result)

Parse an overlay specification from a file

Shows loading an overlay file and accessing its properties.

overlayContent := `overlay: 1.0.0
info:
  title: API Modification Overlay
  version: 1.0.0
actions:
  - target: $.info.title
    update: Enhanced Pet Store API
  - target: $.info.version
    update: 2.0.0`

overlayFile := "temp_overlay.yaml"
if err := os.WriteFile(overlayFile, []byte(overlayContent), 0644); err != nil {
	panic(err)
}
defer func() { _ = os.Remove(overlayFile) }()

overlayDoc, err := overlay.Parse(overlayFile)
if err != nil {
	panic(err)
}

fmt.Printf("Overlay Version: %s\n", overlayDoc.Version)
fmt.Printf("Title: %s\n", overlayDoc.Info.Title)
fmt.Printf("Number of Actions: %d\n", len(overlayDoc.Actions))

for i, action := range overlayDoc.Actions {
	fmt.Printf("Action %d Target: %s\n", i+1, action.Target)
}

Validate an overlay specification

Shows loading and validating an overlay specification for correctness.

invalidOverlay := `overlay: 1.0.0
info:
  title: Invalid Overlay
actions:
  - target: $.info.title
    description: Missing update or remove`

overlayFile := "temp_invalid_overlay.yaml"
if err := os.WriteFile(overlayFile, []byte(invalidOverlay), 0644); err != nil {
	panic(err)
}
defer func() { _ = os.Remove(overlayFile) }()

overlayDoc, err := overlay.Parse(overlayFile)
if err != nil {
	fmt.Printf("Parse error: %s\n", err.Error())
	return
}

validationErr := overlayDoc.Validate()
if validationErr != nil {
	fmt.Println("Validation errors:")
	fmt.Printf("  %s\n", validationErr.Error())
} else {
	fmt.Println("Overlay specification is valid!")
}

Use remove actions in overlays

Shows removing specific paths and properties from an OpenAPI document.

openAPIContent := `openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
  /users/{id}:
    get:
      summary: Get user
  /admin:
    get:
      summary: Admin endpoint
      deprecated: true`

overlayContent := `overlay: 1.0.0
info:
  title: Cleanup Overlay
  version: 1.0.0
actions:
  - target: $.paths['/admin']
    remove: true`

openAPIFile := "temp_openapi.yaml"
overlayFile := "temp_overlay.yaml"
if err := os.WriteFile(openAPIFile, []byte(openAPIContent), 0644); err != nil {
	panic(err)
}
if err := os.WriteFile(overlayFile, []byte(overlayContent), 0644); err != nil {
	panic(err)
}
defer func() { _ = os.Remove(openAPIFile) }()
defer func() { _ = os.Remove(overlayFile) }()

overlayDoc, err := overlay.Parse(overlayFile)
if err != nil {
	panic(err)
}

openAPINode, err := loader.LoadSpecification(openAPIFile)
if err != nil {
	panic(err)
}

err = overlayDoc.ApplyTo(openAPINode)
if err != nil {
	panic(err)
}

var buf strings.Builder
encoder := yaml.NewEncoder(&buf)
encoder.SetIndent(2)
err = encoder.Encode(openAPINode)
if err != nil {
	panic(err)
}

fmt.Printf("Document after removing deprecated endpoint:\n%s", buf.String())

Contributing

This repository is maintained by Speakeasy, but we welcome and encourage contributions from the community to help improve its capabilities and stability.

How to Contribute

1. Open Issues: Found a bug or have a feature suggestion? Open an issue to describe what you'd like to see changed.

2. Pull Requests: We welcome pull requests! If you'd like to contribute code:

   • Fork the repository
   • Create a new branch for your feature/fix
   • Submit a PR with a clear description of the changes and any related issues

3. Feedback: Share your experience using the packages or suggest improvements.

All contributions, whether they're bug reports, feature requests, or code changes, help make this project better for everyone.

Please ensure your contributions adhere to our coding standards and include appropriate tests where applicable.