[Pulp-dev] proposed changes to Pulp 3 auto generated docs

[Dennis Kliban]

I am working on improving the OpenAPI 2.0 schema for Pulp 3. I would like
to get some input on the improvements I am proposing. The schema is used to
generate our REST API documentation as well as the bindings with
swagger-codegen.

The docs generated from our current schema look something like this:

GET /repositories/{repository_pk}/versions/{number}/content/
<https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#get--repositories-repository_pk-versions-number-content->
Parameters:

   - *number* (*integer*) –
   - *repository_pk* (*string*) –

Status Codes:

   - 200 OK
   <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1> –


Since Pulp identifies resources using their HREFs, I am proposing that the
schema produce documentation that states:

GET /{repository_version_href}/content/
Parameters:

   - *repository_version_href* (string) – HREF for the repository version

Status Codes:

   - 200 OK
   <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1> –


Thoughts? Ideas? All feedback is welcome. Thank you!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180718/c6bcd68d/attachment.htm>