https://kotlinlang.org logo
Title
r

Ricardo

08/28/2019, 1:14 PM
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
Something along the lines of:
Which outputs something like:
d

dave

08/29/2019, 7:48 AM
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`
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)
r

Ricardo

08/29/2019, 4:09 PM
Here is an example of an extension that modifies the root OpenAPI object:
Here is another example that modifies the
info
OpenAPI object: https://docs.apimatic.io/advanced/swagger-codegen-extensions/
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,
d

dave

08/29/2019, 4:28 PM
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.
It could get rather knarly though
r

Ricardo

08/29/2019, 4:29 PM
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.
But then, what if the user wants to do that.
d

dave

08/30/2019, 7:36 AM
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.
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. 🙂
I'm releasing 3.179.0 now which includes support for OpenApiExtensions and multiple security models in each route (both
and()
and
or()
r

Ricardo

08/30/2019, 9:22 AM
That looks perfect, thanks!