[archived] "Swagger API Reference" docs discussion

[giscus[bot]]

argo-workflows/swagger/

https://argoproj.github.io/argo-workflows/swagger/

[sairamkrish]

To view the above Swagger API docs, use following steps:

• Open - https://editor.swagger.io/
  • Goto File > Import URL > https://raw.githubusercontent.com/argoproj/argo-workflows/master/api/openapi-spec/swagger.json

[terrytangyuan]

Would you like to add this to the documentation that helps new users?

[dixon1e]

As a new user, it is confusing that almost all the documentation is in YAML, but the API is in REST. I continue to search for documentation that explains what the correspondence is meant to be, from YAML to JSON. For example, I immediately tried Python to change from YAML to dict to JSON and this is not correct. Of course, "lists" for one thing have to be correctly unpacked and so on.

Is there any documentation at all for the REST API other than "read the OpenAPI spec"?

[ad-m-ss]

You can also link directly to editor: https://editor.swagger.io/?url=https://raw.githubusercontent.com/argoproj/argo-workflows/master/api/openapi-spec/swagger.json

Alternatively you can also link to Redoc UI: https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/argoproj/argo-workflows/master/api/openapi-spec/swagger.json

[agilgur5]

Note that as of #10923, the API docs page now has an embedded Swagger UI: https://argo-workflows.readthedocs.io/en/latest/swagger/

Is there any documentation at all for the REST API other than "read the OpenAPI spec"?

There are a few different examples in this same section of the "User Guide", in various pages of the "API" subsection (this is one of those pages as well).

But for schema specifics, no, the spec is the only doc. It is a complete spec, so it has everything, but it is missing descriptions that would be quite helpful. PRs welcome!