Fix swagger spec

[IvanGoncharov]

I'm working on open catalog of REST API specifications.
And I really want to add your API into it, but it don't pass validation.
As first step, I fixed some obvious mistakes.

[d00rman]

Thank you @IvanGoncharov for the contribution! And the catalogue project looks very very interesting! We'd love be part of it.

[Pchelolo]

@IvanGoncharov Thank you for the patch.

BTW Which tool are you using for spec validation? This one?

[IvanGoncharov]

@Pchelolo validator-badge is definitely step in right direction. But it validate only against official JSON Schema.
I use sway which has a lot of additional semantic validations.

[IvanGoncharov]

@Pchelolo @d00rman Next problem that I see is optional path parameters. Like for example: /{module:transform}/html/to/wikitext{/title}{/revision}
Swagger spec(see this) doesn't support them:

If the parameter is in path, this property is required and its value MUST be true

Simplest solution would be to split function into few, like for example /{module:transform}/html/to/wikitext{/title}{/revision} will be spitted into:

• /{module:transform}/html/to/wikitext
• /{module:transform}/html/to/wikitext/{title}
• /{module:transform}/html/to/wikitext/{title}/{revision}

Code duplication could be reduced by sharing parameters and responces.
If you agree with such solution I can submit a PR.

[gwicke]

@IvanGoncharov: We proposed optional path & more generally RFC 6570 support in OAI/OpenAPI-Specification#93. There are quite a few other tasks requesting this, and there were some noises from the swagger folks that they'd add it in the next version of the spec.

I don't think that bloating our docs with a lot of overlapping routes would be desirable. Maybe we could find a way to automatically expand routes using some RFC 6570 features to a verbose Swagger 2.0 spec & then list that in your site?

[IvanGoncharov]

@gwicke I think first step is to explicitly mark that you using such extension and it not done by mistake.
Swagger support specification extensions so I propose add something like x-hasOptionalPathParamets: true in top-level of specification.
I think separate NPM package which do expansion will be good alternative and it could be reused by others. I imagine it taking swagger finding all paths that have {/var} template in them checking that required is false for appropriate parameters and splitting such paths and finally remove x-hasOptionalPathParamets. It will also benefit you by allowing to validate your spec and also use it with unpatched libraries and tools.
In future we can added support for {+var} into the same lib.
What do you think?