-
Bug
-
Resolution: Unresolved
-
Minor
-
None
-
SaaS
-
None
-
False
-
None
-
False
-
Not Started
-
Not Started
-
Not Started
-
Not Started
-
Not Started
-
Not Started
Some endpoints show as XML in API docs [1] while they do support JSON and as far as I know we prefer to use JSON in the long term and may not always support XML in future APIs.
For example `Signup Express (Account Create)`. Perhaps we better update swagger comments to remove `xml` part so users are not confused that only XML is supported.
Or change to `json` in case we don't want to support XML in the long term.
In either case, we need to make sure that dynamic calls from documentation will still be working after the change.
[1] https://someprovider-admin.3scale.net/p/admin/api_docs
UPDATE: Also, currently, the Accept header seems to be ignored by the API, it only cares about the extension (.json or .xml).
I think what we could do is to remove the extensions from the paths, and instead rely on the Accept header to determine the desired output Content-Type. We can make it backward-compatible by still allowing the old .xml and .json paths, but in addition to these, support the ones without them.
This would also make the Swagger UI look nice with a selector that allows changing the Accept header.
- is related to
-
THREESCALE-9599 Improvements for 3scale API docs (based on OpenAPI v3)
- Closed
- relates to
-
THREESCALE-5691 Review xml vs. json parameters in "3scale API Documentation"
- To Develop