<div dir="ltr"><div>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. <br></div><div><br></div><div> - The path parameters in the schema don't reflect the parameters our users should be using for identifying the resources available via REST API. <br></div><div><br></div><div> - The path parameters don't have a description in the schema.</div><div><br></div><div>Do others agree with these problem statements? <br></div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 18, 2018 at 9:31 AM, Dennis Kliban <span dir="ltr"><<a href="mailto:dkliban@redhat.com" target="_blank">dkliban@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>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. <br></div><div><br></div><div>The docs generated from our current schema look something like this:</div><div><br></div><div><dt id="m_-2856099422503988817gmail-get--repositories-repository_pk-versions-number-content-">
<code class="m_-2856099422503988817gmail-descname">GET </code><code class="m_-2856099422503988817gmail-descname">/repositories/{repository_pk}/<wbr>versions/{number}/content/</code><a class="m_-2856099422503988817gmail-headerlink" href="https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#get--repositories-repository_pk-versions-number-content-" title="Permalink to this definition" target="_blank"></a></dt>
<dd><table class="m_-2856099422503988817gmail-docutils m_-2856099422503988817gmail-field-list" frame="void" rules="none">
<colgroup><col class="m_-2856099422503988817gmail-field-name">
<col class="m_-2856099422503988817gmail-field-body">
</colgroup><tbody valign="top">
<tr class="m_-2856099422503988817gmail-field-odd m_-2856099422503988817gmail-field"><th class="m_-2856099422503988817gmail-field-name">Parameters:</th><td class="m_-2856099422503988817gmail-field-body"><ul class="m_-2856099422503988817gmail-first m_-2856099422503988817gmail-simple">
<li><strong>number</strong> (<em>integer</em>) – </li>
<li><strong>repository_pk</strong> (<em>string</em>) – </li>
</ul>
</td>
</tr>
<tr class="m_-2856099422503988817gmail-field-even m_-2856099422503988817gmail-field"><th class="m_-2856099422503988817gmail-field-name">Status Codes:</th><td class="m_-2856099422503988817gmail-field-body"><ul class="m_-2856099422503988817gmail-first m_-2856099422503988817gmail-last m_-2856099422503988817gmail-simple">
<li><a class="m_-2856099422503988817gmail-reference m_-2856099422503988817external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" target="_blank">200 OK</a> – </li>
</ul></td></tr></tbody></table></dd><br></div><div> Since Pulp identifies resources using their HREFs, I am proposing that the schema produce documentation that states:</div><div><br></div><div><dt id="m_-2856099422503988817gmail-get--repositories-repository_pk-versions-number-content-">
<code class="m_-2856099422503988817gmail-descname">GET </code><code class="m_-2856099422503988817gmail-descname">/{repository_version_href}/<wbr>content/</code></dt>
<dd><table class="m_-2856099422503988817gmail-docutils m_-2856099422503988817gmail-field-list" frame="void" rules="none">
<colgroup><col class="m_-2856099422503988817gmail-field-name">
<col class="m_-2856099422503988817gmail-field-body">
</colgroup><tbody valign="top">
<tr class="m_-2856099422503988817gmail-field-odd m_-2856099422503988817gmail-field"><th class="m_-2856099422503988817gmail-field-name">Parameters:</th><td class="m_-2856099422503988817gmail-field-body"><ul class="m_-2856099422503988817gmail-first m_-2856099422503988817gmail-simple">
<li><strong>repository_version_href</strong> (string) – HREF for the repository version<br></li>

</ul>
</td>
</tr>
<tr class="m_-2856099422503988817gmail-field-even m_-2856099422503988817gmail-field"><th class="m_-2856099422503988817gmail-field-name">Status Codes:</th><td class="m_-2856099422503988817gmail-field-body"><ul class="m_-2856099422503988817gmail-first m_-2856099422503988817gmail-last m_-2856099422503988817gmail-simple">
<li><a class="m_-2856099422503988817gmail-reference m_-2856099422503988817external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" target="_blank">200 OK</a> – </li>
</ul></td></tr></tbody></table></dd></div><div><br></div><div>Thoughts? Ideas? All feedback is welcome. Thank you!<br></div></div>
</blockquote></div><br></div>