Swagger-ui: Support YAML file loading

Created on 20 Sep 2014 · 14Comments · Source: swagger-api/swagger-ui

The current 2.0 spec should be supported with either YAML or JSON.

Source

fehguy

Most helpful comment

https://www.npmjs.com/package/yamljs
http://yamltojson.com/
http://www.commandlinefu.com/commands/view/12218/convert-yaml-to-json

Also, contrary all my rant here, we are going to support loading of YAML here.
https://github.com/swagger-api/swagger-ui/issues/1047

webron on 5 May 2015

👍2 👀1 😄1

All 14 comments

Any word on this?

ngConsulti on 28 Oct 2014

I'm not sure we're going to support it after all. There's really no reason to support it.

webron on 28 Oct 2014

Why is there no reason to support it? If a projects's API definition is in Swagger 2.0 YAML format, shouldn't Swagger UI be able to load it?

ngConsulti on 28 Oct 2014

The specification is in JSON, not YAML. YAML is used by the swagger-editor as a more human-friendly way to manually write the spec. Since it exports it as JSON, there's no real reason to add special support for YAML. I certainly don't think the various tools out there need to add support for YAML on top of JSON as that's just development overhead.

webron on 28 Oct 2014

Oh! My misunderstanding then. The YAML-first orientation of the swagger-editor and the swagger-spec v2.0 examples in YAML lead me to believe that JSON and YAML were interchangeable. Guess not.

ngConsulti on 28 Oct 2014

👍1

It was important for us to provide a YAML based editor, which is why you see the examples in the swagger-spec repository. The main description on that repository also mentions that the files are JSON-based and there is not mention of YAML, but perhaps that should be further emphasized.

Honestly, I have two main concerns with the interchangeability between JSON and YAML. The first is the support of the libraries - since Swagger is a standard, there are numerous libraries built around it. You can see a partial list in swagger-spec's main README. Expecting various tools to provide support for both is probably too much (especially considering the next point). I don't think we want to add support in _some_ tools as that may lead the community to believe that YAML is a first-class representation and that would again lead to pressure on other libraries to add such support.

The second concern is that we use plenty of JSON-specific representations in the spec, some of which are directly taken from the JSON Schema representation. While they _can_ be represented in YAML, they are not always natural to it, if you know what I mean, and I definitely wouldn't want to have different representation variants for YAML and JSON (for example, the way references/anchoring work in each representation).

Overall, I'm very happy with the swagger-editor's YAML support, but I believe it should stay there. I hope that's clearer now.

webron on 28 Oct 2014

Yes, very clear. I'm a big fan of JSON Schema, so I get you. That said, I'm sure I'm not the only one to be lead astray. Should definitely find a way to make it clear that Swagger 2.0 is a JSON-only format. I'd suggest noting this in swagger-spec, swagger-editor, and swagger-ui in a way that can't be missed!

ngConsulti on 28 Oct 2014

Fair enough. I'd look into how to clarify it further. Thank you for the feedback!

webron on 28 Oct 2014

No problem. Thanks for your part in this awesome project!

ngConsulti on 28 Oct 2014

Since we're currently not going to support this, I'm going to close it.

webron on 8 Jan 2015

Are there any tools that can convert a standalone YAML file into JSON? I take the point about not updating all the dependent libraries and tools to be able to take YAML as input, but it would be good to have a 1 step command line process to handle conversion so YAML can be used as the origin of a spec outside the editor.