<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="gmail-get--repositories-repository_pk-versions-number-content-">
<code class="gmail-descname">GET </code><code class="gmail-descname">/repositories/{repository_pk}/versions/{number}/content/</code><a class="gmail-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"></a></dt>
<dd><table class="gmail-docutils gmail-field-list" frame="void" rules="none">
<colgroup><col class="gmail-field-name">
<col class="gmail-field-body">
</colgroup><tbody valign="top">
<tr class="gmail-field-odd gmail-field"><th class="gmail-field-name">Parameters:</th><td class="gmail-field-body"><ul class="gmail-first gmail-simple">
<li><strong>number</strong> (<em>integer</em>) – </li>
<li><strong>repository_pk</strong> (<em>string</em>) – </li>
</ul>
</td>
</tr>
<tr class="gmail-field-even gmail-field"><th class="gmail-field-name">Status Codes:</th><td class="gmail-field-body"><ul class="gmail-first gmail-last gmail-simple">
<li><a class="gmail-reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">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="gmail-get--repositories-repository_pk-versions-number-content-">
<code class="gmail-descname">GET </code><code class="gmail-descname">/{repository_version_href}/content/</code></dt>
<dd><table class="gmail-docutils gmail-field-list" frame="void" rules="none">
<colgroup><col class="gmail-field-name">
<col class="gmail-field-body">
</colgroup><tbody valign="top">
<tr class="gmail-field-odd gmail-field"><th class="gmail-field-name">Parameters:</th><td class="gmail-field-body"><ul class="gmail-first gmail-simple">
<li><strong>repository_version_href</strong> (string) – HREF for the repository version<br></li>

</ul>
</td>
</tr>
<tr class="gmail-field-even gmail-field"><th class="gmail-field-name">Status Codes:</th><td class="gmail-field-body"><ul class="gmail-first gmail-last gmail-simple">
<li><a class="gmail-reference external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1">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>