OpenAPI 3 support #340

Erando89 · 2018-09-27T13:35:24Z

Will there be OpenAPI 3 support in near feature?

rolandhaas · 2018-12-20T08:01:07Z

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 base or common package
(+) 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

Erando89 · 2018-12-20T09:23:03Z

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.

rolandhaas · 2018-12-20T11:45:19Z

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

jmini · 2019-02-08T10:06:29Z

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.

theletterf · 2019-05-15T07:45:00Z

No updates on this? :(

RobWin · 2019-05-15T07:47:37Z

Please see #312

balajiv113 · 2019-12-21T05:09:24Z

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 ?

austek · 2019-12-23T09:44:26Z

already started work on branch https://github.com/Swagger2Markup/swagger2markup/tree/feature/open_api_v3_support

balajiv113 · 2019-12-24T05:53:19Z

@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.

austek · 2019-12-24T16:10:41Z

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

* Use Asciidoc AST to create OpenApi v3 support * Add `Overview` information * Add `Servers` information * Fix document authors * Fix document authors * Add `Servers` information * Add `Servers` information * Add `Servers` information * Add `Servers` information * Add `Path Parameters` information * Add `Path Parameters` information * Add `Path Responses Links` information * Add `Tags` information * Add `Comonents.Schemas` information * Add `Comonents.Parameters` information * Add `External Docs` information * Add `Components Responses` information * Add `Components Headers` information * Add `Components Links` information * Delete unused test fixtures * Change asciidoctorJ dependency to asciidoctorj-api, to remove the the need for JRuby

TehBakker · 2020-02-06T13:40:52Z

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.

* Use Asciidoc AST to create OpenApi v3 support * Add `Overview` information * Add `Servers` information * Fix document authors * Fix document authors * Add `Servers` information * Add `Servers` information * Add `Servers` information * Add `Servers` information * Add `Path Parameters` information * Add `Path Parameters` information * Add `Path Responses Links` information * Add `Tags` information * Add `Comonents.Schemas` information * Add `Comonents.Parameters` information * Add `External Docs` information * Add `Components Responses` information * Add `Components Headers` information * Add `Components Links` information * Delete unused test fixtures * Change asciidoctorJ dependency to asciidoctorj-api, to remove the the need for JRuby

vmaks · 2021-10-14T15:15:27Z

Hi, thanks for your efforts.
Do you have any updates about this issue?

jaeddy mentioned this issue Feb 11, 2019

Update to OpenAPI 3.0 ga4gh/data-repository-service-schemas#230

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenAPI 3 support #340

OpenAPI 3 support #340

Erando89 commented Sep 27, 2018

rolandhaas commented Dec 20, 2018

Erando89 commented Dec 20, 2018 •

edited

Loading

rolandhaas commented Dec 20, 2018

jmini commented Feb 8, 2019

theletterf commented May 15, 2019

RobWin commented May 15, 2019

balajiv113 commented Dec 21, 2019

austek commented Dec 23, 2019

balajiv113 commented Dec 24, 2019

austek commented Dec 24, 2019 •

edited

Loading

TehBakker commented Feb 6, 2020

vmaks commented Oct 14, 2021

OpenAPI 3 support #340

OpenAPI 3 support #340

Comments

Erando89 commented Sep 27, 2018

rolandhaas commented Dec 20, 2018

Erando89 commented Dec 20, 2018 • edited Loading

rolandhaas commented Dec 20, 2018

jmini commented Feb 8, 2019

theletterf commented May 15, 2019

RobWin commented May 15, 2019

balajiv113 commented Dec 21, 2019

austek commented Dec 23, 2019

balajiv113 commented Dec 24, 2019

austek commented Dec 24, 2019 • edited Loading

TehBakker commented Feb 6, 2020

vmaks commented Oct 14, 2021

Erando89 commented Dec 20, 2018 •

edited

Loading

austek commented Dec 24, 2019 •

edited

Loading