swagger2markup
swagger2markup copied to clipboard
Swagger2Markup
OpenAPI 3 support
As far as I can see this won't be possible without breaking changes.
io.github.swagger2markup.Swagger2MarkupConverter.Context holds the io.swagger.models.Swagger which is openApi 2.0 only. Since the Context is also passed as argument to the SPI component io.github.swagger2markup.spi.Extension this won't work if dependency for io.swagger.core.v3 is included because the models differ between 2.0 and 3.x
In my opinion there are the following options to implement openApi 3.0 support:
-
Breaking change within
io.github.swagger2markup.Swagger2MarkupConverter.Context(+) Code duplication is at minimum (+) No configuration changes for existing users (openApi 2.0 remains default) (+) dynamic configuration based on the input source file (switch 2.0 vs 3.0 handeled internally) (-) Providers of extensions have breaking change -
New Module for openApi 3.0 and refactoring of common code to
baseorcommonpackage (+) no changes for existing users (openApi 2.0 remains default) (-) user must know if the input source is openApi 2.0 or 3.x while configuration (-) SPI for openApi 2.0 and 3.x (-) big refactoring
I would prefer V1 and perform a breaking change once and try to refactor the SPI interface independent of the open Api version (must be validated if possible)
@RobWin: Do you see any other options?
Regards
I've found a better way to convert a OAS3 swagger.yaml to a Documentation, using Swagger Editor.
<html>
<head>
<title>Documentation</title>
<link rel="stylesheet" href="https://raw.githubusercontent.com/swagger-api/swagger-ui/master/dist/swagger-ui.css"/>
<script src="https://raw.githubusercontent.com/swagger-api/swagger-ui/master/dist/swagger-ui-bundle.js" type="text/javascript" ></script>
<script>
function render() {
var ui = SwaggerUIBundle({
url: "link/to/your/swagger.yaml",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}
</script>
</head>
<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>
This works perfectly and results in a document like the right-hand side at Swagger Editor.
Guess I found a better way: Within the new openApi Parser for openApi 3 there's a Converter which can convert from older versions of openApi to the latest version.
- Remove existing swagger dependency from swagger2markup project and switch to the new openApi model internally
compile group: 'io.swagger.core.v3', name: 'swagger-core', version: '2.0.6'
compile group: 'io.swagger.parser.v3', name: 'swagger-parser-v2-converter', version: '2.0.7'
- Pass any incoming source file to the converter to ensure v 3.0.1
- continue as before
I wanted to give your tool a try, but we are using OpenAPI v3, so I guess I will have to dig into the code first.
There is a workaround. Some services offer v3 to v2 transformation (I am using https://www.apimatic.io/ but I guess there are other alternatives)
What @rolandhaas is describing here is correct.
If Swagger2Markup is updated to work with the OpenAPI v3 model (present in io.swagger.core.v3:swagger-models:2.0.6) then It is possible to let Swagger-Parser to do an on-the-fly conversion OpenAPI v2 -> OpenAPI v3.
Swagger-Parser has different jars that can be used, depending on the use-case: doing only parsing of v3 or parsing+conversion of v2. It is just a matter of controlling what you put on the classpath.
Since some rework of Swagger2Markdown is requested, you might also consider using the interfaces defined in Eclipse MicroProfile:
<dependency>
<groupId>org.eclipse.microprofile.openapi</groupId>
<artifactId>microprofile-openapi-api</artifactId>
<version>2.0-MR1</version>
</dependency>
The model is really similar to what Swagger-Core is providing, but following the JavaEE principle, there is a clear API with interfaces and different vendors can implement them.
I have just released a bridge (EMPOA Swagger-Core) that implements the Eclipse MicroProfile interfaces by delegating to the Swagger-Core objects. This means that you can wrap the output of Swagger-Parser into objects that implements the Eclipse MicroProfile interfaces.
Advantage of this approach: decoupling! You program against an API and you can exchange the implementations. For example I have on my roadmap to create a second wrapper for the model used by KaiZen-OpenAPI-Parser. This way you build something that does not depend from a specific parser.
I hope I will find time to work on OpenAPI v3 support in Swagger2Markup. I did not looked at the code of Swagger2Markup yet, so I can not guaranty if I will be able to do it or not.
Hi, i would like to help on this. I can submit a PR for OpenAPI 3 support. What's the plan for OpenAPI 3 ?
Are we going ahead with @rolandhaas comment using OpenAPI 3 convertor to convert swagger 2 to OpenAPI 3 ?
already started work on branch https://github.com/Swagger2Markup/swagger2markup/tree/feature/open_api_v3_support
@austek Ya i checked that branch, if am not wrong the plan is to first implement a asciidoc builder based on asciidoctorj and use it to implement the OpenAPI 3 markdown right ? I have tried used existing markdown-builder to generate complete Overview section for OpenAPI 3. If this is still a option i can extend the implementation and submit the PR for other sections like Paths, Definitions and Security.
Plan is Open Api v3
OpenAPI openAPI = new OpenAPIV3Parser().read("/path/to/file.json");
Document asciiDoc = OpenApi2AsciiDoc.translate(openApi); // Started work on branch refactor/Asciidoctor_ast_implementation
String asciiDocFileContent = asciiDoc.convert();
For Swagger v2
Swagger swagger = new SwaggerParser().read("./path/to/swagger.json");
Document asciiDoc = Swagger2AsciiDoc.translate(swagger); // Doesn't exist yet
String asciiDocFileContent = asciiDoc.convert(); // Same converter as above
Thanks a lot for your work.
Any idea when there will be a first draft of the swagger2markup-maven-plugin using the openApi version to test ? I migrated my project to openApi and finding myself stuck because of this.
