Parser - Swagger - add support for v3

[JonathanMontane]

Swagger v3 will soon be stable. it would be nice to have the possibility to import swagger v3.

[philsturgeon]

Just a heads up that OpenAPI v3.0 is out in the wild now. Also they'll shout at you if you call it Swagger. It's OpenAPI, and Swagger is just some of the tools around it (like the editor, ui, etc).

Anyhow, check it out https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

[MikeRalphson]

I notice this issue is labelled status:on-hold - could someone shed some light as to what this means? I'm interested in working on openapi3 support (as well as Mashery io-docs and Google discovery formats) but don't want to duplicate effort unnecessarily.

[JonathanMontane]

@MikeRalphson I'm working on it (albeit very slowly, thus the status:on-hold). Here's the corresponding PR if you want to contribute or see the progress: JonathanMontane#4

If you want to create additional formats, there are templates for the loaders and parsers to help you create those faster. A parser is a Your format -> API-Flow converter and a loader is a helper for the parser that pre-processes files to normalize inputs. Typically if your format has multiple ways to write something, e.g. you can write a URL either as a string or as an object, this would be the place to use to make the format less variable.

I'd be happy to help you get set up if you want to (I think the setup instructions are missing some step, like yarn install).

[MikeRalphson]

Thanks @JonathanMontane - I've tried both yarn v1.0.2 and npm v5.3.0 which install the node-modules directory somewhat differently and I still get webpack errors on know-your-http-well (which I've resolved for now by patching out the amd module define and reworking it as a common-js module - still not sure why this is necessary on my end) - I've also tried upgrading to webpack v3.5.6 but with no difference.

I'll take a look at your PR, thanks again.

[JonathanMontane]

@MikeRalphson This library wasn't tested on Windows, so it's highly likely that path resolution is indeed buggy. I'll try to have a look into it this week if I get my hands on a Windows machine.

As for the know-your-http-well module, it's a package bundled in by the raml-1-parser maintained by the RAML org, which you can find here: https://github.com/raml-org/raml-js-parser-2/, which is full of problematic packages (all of the code is written in ts, and bundled with a ts compiler instead of being pre-compiled in js, which makes the package size explode). If I recall correctly, this package is not even needed for their tool to work, and it only appears as a commented line in their webpack bundle. It'd be a good idea to raise up an issue with them to see if they can clean up their build process and package.json.

EDIT: It might be that you just need to bump the raml-1-parser version in API-Flow to resolve this issue. Latest version of the raml-1-parser is 1.1.30

[philsturgeon]

I'd dig in and help with this stuff @JonathanMontane but I cannot get anything to run at all: #142

If you could help me out there, I'd be happy to help you out further with OAI 3 and stuff.