New proposal: support for Google Cloud Endpoints `...

# http4k

[Ricardo]

New proposal: support for Google Cloud Endpoints x-google-endpoints extension for OpenAPI: https://cloud.google.com/endpoints/docs/openapi/openapi-extensions#x-google-endpoints

[Ricardo]

Something along the lines of:

Untitled

[Ricardo]

Which outputs something like:

Untitled

[dave]

this seems doable. I'd suggest an interface like this to represent the extension:

package org.http4k.contract.openapi

interface OpenApiExtension {
    val extensionId: String
    fun <NODE> render(): Render<NODE>
}

, which will be used to produce a key/node pair that can be merged into the API JSON docs at the top level - it will also allow people to define their own extensions without importing them into http4k. The OpenAPI2 and 3 objects would need to take a list of these extensions (defaulted to an emptyList to ensure non-breaking API compatability`

[dave]

one thing I would like to know is other examples of OpenApi extensions - the docs seem to indicate that you can have extensions a many levels of the JSON graph, To keep the DSL away from being locked to OpenApi, I think we'll only really be able to support ones at the root level (and not at a path level)

[Ricardo]

Here is an example of an extension that modifies the root OpenAPI object:

[Ricardo]

https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md

[Ricardo]

Here is another example that modifies the info OpenAPI object: https://docs.apimatic.io/advanced/swagger-codegen-extensions/

[Ricardo]

If we're merging JSON nodes, could a OpenApiExtension also merge with non-root objects? This would allow downstream users to modify everything in the Swagger,

[dave]

the merging I was thinking of was simply that you provide a Render<MODE> and that gets kv merged into the root - but I suppose we could actually take the finished NODE and process that instead.

[dave]

It could get rather knarly though

[Ricardo]

I suppose the main risk is a user inadvertently "merges" or overwrites something they want to keep. We could throw an error if a user attempts to over-write pre-existing JSON nodes.

[Ricardo]

But then, what if the user wants to do that.

[dave]

I've added the following interface to cover the ability to extend/modify the JSON document:

interface OpenApiExtension {
    operator fun <NODE> invoke(node: NODE): Render<NODE>
}

. It's currently in master - take a look and let me know if that works for your purposes.

[dave]

There's no defence again screwing up the JSON, but TBH that's a risk that people will need to take for themselves if they decide to implement an extension. 🙂

[Ricardo]

That looks perfect, thanks!