I’m going to write an macro that will provide the possibility to show an Open API documentation based on a Json or Yaml with Swagger. The idea is to use the Swagger-UI project which bring everything needed to develop this.
For this macro the idea is to have 2 main possibility to inject the API description.
We can put the Open API doc in Json or Yaml format in the macro content
We can provide an URL which will provide the information in Json or Yaml format like http://petstore.swagger.io/v2/swagger.json Note that we can also use this way to store the Json file as a page attachment.
For the seconds part as the browser will send an external request it might be sometime needed to use a proxy (to work around the CORS issue), so a parameter named proxy with a boolean will give the possibility to use or not the proxy.
Maybe at some point I could also integrate the Swagger editor as an application.
For the naming I propose to name it swagger or swagger-open-api or maybe open-api-doc.
Thanks for the proposal, that’s an interesting extension.
From what I understand, openapi is the spec, and swagger the implementation.
So I’d be +1 for a openapi repository, possibly with a openapi-swagger submodule.
I don’t know openapi and swagger well but if swagger is just an implementation maybe it should be an {{openapi}} macro which default implementation is based on swagger (and maybe later pass some parameter to choose a different implementation, “renderer” ?).
Yes there are some other implementations and I don’t mind to add a “renderer” parameter when we want to have an other renderer.
The only issue that I see around this (but maybe it’s not really a problem), is that the macro parameters for the initial macro might be really related to Swagger so if at some point we add an other renderer the parameters for the other renderer might be really different.
But yes it could be a good idea to name the macro openapi which is really simple and add a “renderer” parameter when necessary.
If the parameters are very swagger oriented, then indeed it might make sense to have a swagger macro.
The alternative is to have openapi parameters and then a set of unknown parameters (you can do that by implementing RawProperties in your macro parameters class). But since they are unknown, no descriptor is generated for them by default. So you would have to take care of the ParameterDescriptor map yourself for those if you want to have parameter pickers in the WYSIWYG for them.
This is not about implementing the openapi spec (it’s about using a specific tool implementing the openapi spec).
Even if we have several implementations of the openapi spec using different libraries (swagger, etc), they wouldn’t have the same release cycle and it doesn’t make sense to have them in the same repo. OTOH it makes sense that we have a swagger repo to put stuff related to swagger in a common place since it’s likely that they may share stuff.
This feels like YAGNI. Let’s first have 2 or more repos implementing some openapi stuff and then see if they share something before deciding to group them together and share the same release cycle.