Adapted file for use in editor.swagger.io - Githubissues

maasglobal / maas-tsp-api

WhimApp TSP (Transport Service Provider) Open API

https://maasglobal.github.io/

MIT License

16 stars 18 forks source link

Adapted file for use in editor.swagger.io #27

Closed ChristianMaehler closed 6 years ago

ChristianMaehler commented 6 years ago

I didn't succeed to import the JSON file in editor.swagger.io. I solved the problem like this:

import the yml file into editor.swagger.io ==> success
export it without modification as JSON in file2.json
import the file2.json in editor.swagger.io ==> success
File can now be used https://editor.swagger.io

The pull request comprises the file2.json content without further modifications. Hope that it is useful for you.

brylie commented 6 years ago

For what it's worth, the title fields in the schema were to improve the appearance of the documentation when rendered in Swagger UI. Please leave the title fields in place.

ChristianMaehler commented 6 years ago

Oh, I didn't remove the titles manually - I didn't change anything :-) I only imported your yml and exported it again as json . It was done automatically in the editor.swagger.io ... as far as I can see in the diff, the parameters are sometimes changed in location in the JSON; I didn't check whether there were really removed parameters.

brylie commented 6 years ago

OK, just double check. If they are not removed, we can merge. Otherwise, just add them back.

brylie commented 6 years ago

I think the problem is that the YML and JSON files are out of sync. The JSON file had 'title' attributes for many of the schema items, while the YML file doesn't. Please consider re-adding the title attributes, so we don't lose those.

brylie commented 6 years ago

Upon reflection, I realize that we should probably only maintain one copy of the specification in a single format. Since YAML is easy to read, and supported by Swagger Editor, I offer that we should actually remove the JSON version from this repository.

What are your thoughts @ChristianMaehler?

ChristianMaehler commented 6 years ago

@brylie Although I'm a big fan of JSON :-) , I find it hard to read for an OpenAPI specification; YAML seems to be much more readable. In addition, it will be easier to maintain one version - so, I fully agree. I don't know whether there are some pitfalls using YML only, but atm I can't see any. So my vote is: yes, remove the JSON and keep the YAML.

brylie commented 6 years ago

@ChristianMaehler thanks for your input. Would you like to remove the JSON as part of this PR, so you get credit for your contribution?

If you remove the JSON and push the change, I will review/merge this PR :-)

brylie commented 6 years ago

Closing this PR, as I have removed the JSON spec from the repo.