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

Dennis Kliban dkliban at redhat.com
Wed Jul 18 17:05:45 UTC 2018


I was asked on IRC to state what problems the proposed changes are trying
to address. There are two problems I see with the current OpenAPI 2.0
schema Pulp's REST API provides.

 - The path parameters in the schema don't reflect the parameters our users
should be using for identifying the resources available via REST API.

 - The path parameters don't have a description in the schema.

Do others agree with these problem statements?



On Wed, Jul 18, 2018 at 9:31 AM, Dennis Kliban <dkliban at redhat.com> wrote:

> 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/f66f5c16/attachment.htm>


More information about the Pulp-dev mailing list