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 <dkli...@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@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev
