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

[Daniel Alley]

Keep in mind that as of yesterday, unless we revert the change, we are
using Integers IDs instead of UUIDs

https://github.com/pulp/pulp/pull/3549

On Wed, Jul 18, 2018 at 9:57 PM, Bihan Zhang <bizhang at redhat.com> wrote:

>
>
> On Wed, Jul 18, 2018 at 1:05 PM, Dennis Kliban <dkliban at redhat.com> wrote:
>
>> 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.
>>
>
> I'm not convinced that we should use hrefs as the sole identifiers for the
> resources.
>
> Here are the reasons I see that we use hrefs as identifiers in a REST API
> context:
>     1. Each href provides full context into the resource it identifies.
> When given a href you would know exactly which resource it is referencing
> and would never run into the issue of: what is this {uuid} because you know
> it is a 'repositories/{uuid}'
>     2. discoverability, you know exactly how to access resources from
> hitting the root url (and in a webui can just click)
>     3. You would not need to construct urls from templates
>
> But things are different if we look at it from a bindings/client context.
> The difference is mainly due to how discoverability is done: in the REST
> API context the user has little prior knowledge to what resources are
> available, and how to access theses resoruces. But the bindings/client are
> generated from the schema, which defines exactly how resources are
> structured, and what the context of each {uuid} is.
>
>     1. Given an {uuid} the client/bindings knows exactly what resource
> this {uuid} refers to.  With hrefs there would be redundant information
> pulp.repositories('repositories/{uuid}') (why do I need to specify
> repositories twice?)
>     2. Discoverability is done with the schema which contains all the
> information about available resources/endpoints
>     3. URL construction is done by the client, so the user would also
> never need to do any url construction themselves (unless we continue to
> force href only identifiers, in which case they might have to do some url
> construction to pass as arguments)
>
> I don't think hrefs and uuid identifiers are mutually exclusive. I propose
> that we extend HyperlinkedRelatedFields to accept either href or uuid, and
> map these HyperlinkedRelatedFields to each other in the schema with openapi
> definition objects [0].
>
> [0] https://github.com/OAI/OpenAPI-Specification/blob/
> master/versions/2.0.md#responses-definitions-object
>
>
>>
>>  - The path parameters don't have a description in the schema.
>>
>> +1 to updating the schema descriptions for these parameters
>
>
>> 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!
>>>
>>
>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>>
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180719/59b8b5a6/attachment.htm>