feat: add support for OpenAPI Overlay

In the past, users wishing to override specific configuration, for
instance taking advantage of extensions such as `x-go-type` would need
to modify the OpenAPI specification they are using.

In a lot of cases, this OpenAPI specification would be produced by a
different team to the consumers (or even a different company) and so
asking them to make changes like this were unreasonable.

This would lead to the API consumers needing to vendor the specification
from the producer (which is our recommendation anyway) and then make any
number of local changes to the specification to make it generate code
that looks reasonable.

However, in the case that a consumer would update their specification,
they would likely end up with a number of merge conflicts.

With these changes, it is now possible to make changes to the input
OpenAPI specification _without needing to modify it directly_.

This takes advantage of the OpenAPI Overlay specification[0], which is a
stable specification, and is ready for wider implementation.

This uses Speakeasy's implementation, which is noted as an "alpha"
implementation.

We introduce a new function, `LoadSwaggerWithOverlay`, which performs
the wrangling of the Overlay on top of the specification we're pointing
to, and make sure we wire in the ability to configure the path, as well
as whether we want to relax the "strict" validation the Overlay library
provides.

Closes oapi-codegen#1553.

[0]: https://github.com/OAI/Overlay-Specification

Author: jamietanna

cmd/oapi-codegen/oapi-codegen.go

@@ -281,7 +281,17 @@ func main() {
 		return
 	}
 
-	swagger, err := util.LoadSwagger(flag.Arg(0))
+	overlayOpts := util.LoadSwaggerWithOverlayOpts{
+		Path: opts.OutputOptions.Overlay.Path,
+		// default to strict, but can be overridden
+		Strict: true,
+	}
+
+	if opts.OutputOptions.Overlay.Strict != nil {
+		overlayOpts.Strict = *opts.OutputOptions.Overlay.Strict
+	}
+
+	swagger, err := util.LoadSwaggerWithOverlay(flag.Arg(0), overlayOpts)
 	if err != nil {
 		errExit("error loading swagger spec in %s\n: %s\n", flag.Arg(0), err)
 	}

configuration-schema.json

@@ -196,6 +196,24 @@
             "ToCamelCaseWithDigits",
             "ToCamelCaseWithInitialisms"
           ]
+        },
+        "overlay": {
+          "type": "object",
+          "description": "Overlay defines configuration for the OpenAPI Overlay (https://github.com/OAI/Overlay-Specification) to manipulate the OpenAPI specification before generation. This allows modifying the specification without needing to apply changes directly to it, making it easier to keep it up-to-date.",
+          "properties": {
+            "path": {
+              "description": "The path to the Overlay file",
+              "type": "string"
+            },
+            "strict": {
+              "type": "boolean",
+              "description": "Strict defines whether the Overlay should be applied in a strict way, highlighting any actions that will not take any effect. This can, however, lead to more work when testing new actions in an Overlay, so can be turned off with this setting.",
+              "default": true
+            }
+          },
+          "required": [
+            "path"
+          ]
         }
       }
     },

examples/authenticated-api/stdhttp/go.mod

@@ -16,6 +16,7 @@ require (
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.2.0 // indirect
+	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
 	github.com/go-openapi/jsonpointer v0.21.0 // indirect
 	github.com/go-openapi/swag v0.23.0 // indirect
 	github.com/goccy/go-json v0.10.2 // indirect
@@ -32,6 +33,8 @@ require (
 	github.com/perimeterx/marshmallow v1.1.5 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/speakeasy-api/openapi-overlay v0.9.0 // indirect
+	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
 	golang.org/x/crypto v0.22.0 // indirect
 	golang.org/x/mod v0.17.0 // indirect
 	golang.org/x/text v0.15.0 // indirect

examples/authenticated-api/stdhttp/go.sum

@@ -41,6 +41,7 @@ require (
 	github.com/cloudwego/iasm v0.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.2.0 // indirect
+	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
 	github.com/fatih/structs v1.1.0 // indirect
 	github.com/flosch/pongo2/v4 v4.0.2 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
@@ -90,6 +91,7 @@ require (
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/schollz/closestmatch v2.1.0+incompatible // indirect
 	github.com/sirupsen/logrus v1.8.1 // indirect
+	github.com/speakeasy-api/openapi-overlay v0.9.0 // indirect
 	github.com/tdewolff/minify/v2 v2.12.9 // indirect
 	github.com/tdewolff/parse/v2 v2.6.8 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
@@ -100,6 +102,7 @@ require (
 	github.com/valyala/tcplisten v1.0.0 // indirect
 	github.com/vmihailenco/msgpack/v5 v5.3.5 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
+	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
 	github.com/yosssi/ace v0.0.5 // indirect
 	golang.org/x/arch v0.8.0 // indirect
 	golang.org/x/crypto v0.23.0 // indirect

examples/go.mod

@@ -7,6 +7,7 @@ replace github.com/oapi-codegen/oapi-codegen/v2 => ../../../
 require github.com/oapi-codegen/oapi-codegen/v2 v2.0.0-00010101000000-000000000000
 
 require (
+	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
 	github.com/getkin/kin-openapi v0.127.0 // indirect
 	github.com/go-openapi/jsonpointer v0.21.0 // indirect
 	github.com/go-openapi/swag v0.23.0 // indirect
@@ -15,6 +16,8 @@ require (
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
 	github.com/perimeterx/marshmallow v1.1.5 // indirect
+	github.com/speakeasy-api/openapi-overlay v0.9.0 // indirect
+	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
 	golang.org/x/mod v0.17.0 // indirect
 	golang.org/x/text v0.15.0 // indirect
 	golang.org/x/tools v0.21.0 // indirect