feat(ws): fix swagger warnings and only generate json output

[liavweiss]

This fix has no GitHub issue and will fix this:
While you put our swagger yaml into https://editor.swagger.io/, you will get a few warnings popping up.

This pr will not fix the "example" warning for this reason:
In Swagger 2.0 example should be with x- example, the issue is in swaggo/swag recognize only example() in the documentation above each function, and it will generate example: in the yaml file.

Bottom line:
It works fine in Swagger UI, but causes errors in Swagger Editor, and I dont think it's a blocker in our project.

[andyatmiami]

Maybe slightly out of scope - but I feel we should change our Makefile to also leverage --outputTypes

I would suggest we go with: go,json - I see no reason to write out both json + yaml - and at least in the Swagger world - JSON feels like the more natural format to me... but could easily be talked into go,yaml with no further debate...

We probably don't really need the .go output - but I like the idea of having it should we ever need/want to mess with stuff programmatically.

[andyatmiami]

This is certainly an open discussion on whether or not we'd want to do this (and/or how important it is to adhere to Swagger 2.0 spec) - but if we really want to resolve the warnings about the example attribute - it seems we can do it as such:

By leveraging the extensions(...) construct - this does render appropriately in the client:

So, if I make a global search-and-replace on your branch - substituting example( with extensions(x-example=) - that then allows the generated JSON to "be clean" in the Swagger Editor

[liavweiss]

@andyatmiami Regarding the x-example, you are right (Im sorry I don't know how I missed that) - will be fixed.

Regarding the swagg init output: I’ll drop the YAML output - since the tooling (including the auto type generation) works fine with JSON and we’re not relying on YAML for anything specific.
We can add it in the future if necessary.

[andyatmiami]

/ok-to-test

[andyatmiami]

/lgtm

Verified now that the generated swagger.json file reports no errors when pasted into Swagger Editor

[thesuperzapper]

Thanks @liavweiss and @andyatmiami

/approve

[google-oss-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: thesuperzapper

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [thesuperzapper]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment