Skip to content

Commit

Permalink
RFC section links
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralfhandl
ralfhandl committed Jul 23, 2024
1 parent d47d9ef commit 4b1c40f
Show file tree
Hide file tree
Showing 7 changed files with 92 additions and 92 deletions.
38 changes: 19 additions & 19 deletions oas/latest.html
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion oas/v2.0.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -274,7 +274,7 @@ <h1 id="title" class="title">OpenAPI Specification v2.0 </h1> <h2 id="subtitle"
application/vnd.github.v3.patch
</code></pre>
</section><section id="http-status-codes"><div class="header-wrapper"><h3 id="x5-3-http-status-codes"><bdi class="secno">5.3 </bdi><dfn id="dfn-http-status-codes" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">HTTP Status Codes</dfn></h3><a class="self-link" href="#http-status-codes" aria-label="Permalink for Section 5.3"></a></div>
<p>The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7231" title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">RFC7231</a></cite>] and in the <a href="http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">IANA Status Code Registry</a>.</p>
<p>The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7231" title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">RFC7231</a></cite>] <a href="https://tools.ietf.org/html/rfc7231#section-6">Section 6</a> and in the <a href="http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">IANA Status Code Registry</a>.</p>
</section></section><section id="specification"><div class="header-wrapper"><h2 id="x6-specification"><bdi class="secno">6. </bdi>Specification</h2><a class="self-link" href="#specification" aria-label="Permalink for Section 6."></a></div>
<section id="format"><div class="header-wrapper"><h3 id="x6-1-format"><bdi class="secno">6.1 </bdi>Format</h3><a class="self-link" href="#format" aria-label="Permalink for Section 6.1"></a></div>
<p>The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to
Expand Down
26 changes: 13 additions & 13 deletions oas/v3.0.0.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -254,7 +254,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
</code></pre>
</section><section id="http-status-codes"><div class="header-wrapper"><h3 id="x3-4-http-status-codes"><bdi class="secno">3.4 </bdi><dfn id="dfn-http-status-codes" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">HTTP Status Codes</dfn></h3><a class="self-link" href="#http-status-codes" aria-label="Permalink for Section 3.4"></a></div>
<p>The HTTP Status Codes are used to indicate the status of the executed operation.
The available status codes are defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7231" title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">RFC7231</a></cite>] and registered status codes are listed in the <a href="http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">IANA Status Code Registry</a>.</p>
The available status codes are defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7231" title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">RFC7231</a></cite>] <a href="https://tools.ietf.org/html/rfc7231#section-6">Section 6</a> and registered status codes are listed in the <a href="http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">IANA Status Code Registry</a>.</p>
</section></section><section id="specification"><div class="header-wrapper"><h2 id="x4-specification"><bdi class="secno">4. </bdi>Specification</h2><a class="self-link" href="#specification" aria-label="Permalink for Section 4."></a></div>
<section id="versions"><div class="header-wrapper"><h3 id="x4-1-versions"><bdi class="secno">4.1 </bdi>Versions</h3><a class="self-link" href="#versions" aria-label="Permalink for Section 4.1"></a></div>
<p>The OpenAPI Specification is versioned using <a href="http://semver.org/spec/v2.0.0.html">Semantic Versioning 2.0.0</a> (semver) and follows the semver specification.</p>
Expand Down Expand Up @@ -374,7 +374,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<p>Throughout the specification <code>description</code> fields are noted as supporting CommonMark markdown formatting.
Where OpenAPI tooling renders rich text it <em class="rfc2119">MUST</em> support, at a minimum, markdown syntax as described by <a href="http://spec.commonmark.org/0.27/">CommonMark 0.27</a>. Tooling <em class="rfc2119">MAY</em> choose to ignore some CommonMark features to address security concerns.</p>
</section><section id="relative-references-in-urls"><div class="header-wrapper"><h3 id="x4-6-relative-references-in-urls"><bdi class="secno">4.6 </bdi>Relative References in URLs</h3><a class="self-link" href="#relative-references-in-urls" aria-label="Permalink for Section 4.6"></a></div>
<p>Unless specified otherwise, all properties that are URLs <em class="rfc2119">MAY</em> be relative references as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>].
<p>Unless specified otherwise, all properties that are URLs <em class="rfc2119">MAY</em> be relative references as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-4.2">Section 4.2</a>.
Relative references are resolved using the URLs defined in the <a href="#server-object"><code>Server Object</code></a> as a Base URI.</p>
<p>Relative references used in <code>$ref</code> are processed as per <a href="https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03">JSON Reference</a>, using the URL of the current document as the base URI. See also the <a href="#reference-object">Reference Object</a>.</p>
</section><section id="schema"><div class="header-wrapper"><h3 id="x4-7-schema"><bdi class="secno">4.7 </bdi>Schema</h3><a class="self-link" href="#schema" aria-label="Permalink for Section 4.7"></a></div>
Expand Down Expand Up @@ -1240,7 +1240,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<tr>
<td><span id="operationRequestBody"></span>requestBody</td>
<td style="text-align:center"><a href="#request-body-object">Request Body Object</a> | <a href="#reference-object">Reference Object</a></td>
<td>The request body applicable for this operation. The <code>requestBody</code> is only supported in HTTP methods where the HTTP 1.1 specification [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7231" title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">RFC7231</a></cite>] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, <code>requestBody</code> <em class="rfc2119">SHALL</em> be ignored by consumers.</td>
<td>The request body applicable for this operation. The <code>requestBody</code> is only supported in HTTP methods where the HTTP 1.1 specification [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7231" title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">RFC7231</a></cite>] <a href="https://tools.ietf.org/html/rfc7231#section-4.3.1">Section 4.3.1</a> has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, <code>requestBody</code> <em class="rfc2119">SHALL</em> be ignored by consumers.</td>
</tr>
<tr>
<td><span id="operationResponses"></span>responses</td>
Expand Down Expand Up @@ -1420,7 +1420,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<ul>
<li>path - Used together with <a href="#path-templating">Path Templating</a>, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in <code>/items/{itemId}</code>, the path parameter is <code>itemId</code>.</li>
<li>query - Parameters that are appended to the URL. For example, in <code>/items?id=###</code>, the query parameter is <code>id</code>.</li>
<li>header - Custom headers that are expected as part of the request. Note that [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7230" title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">RFC7230</a></cite>] states header names are case insensitive.</li>
<li>header - Custom headers that are expected as part of the request. Note that [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7230" title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">RFC7230</a></cite>] <a href="https://tools.ietf.org/html/rfc7230#page-22">Page 22</a> states header names are case insensitive.</li>
<li>cookie - Used to pass a specific cookie value to the API.</li>
</ul>
</section><section id="fixed-fields-9"><div class="header-wrapper"><h5 id="x4-7-12-2-fixed-fields"><bdi class="secno">4.7.12.2 </bdi>Fixed Fields</h5><a class="self-link" href="#fixed-fields-9" aria-label="Permalink for Section 4.7.12.2"></a></div>
Expand Down Expand Up @@ -1489,7 +1489,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<tr>
<td><span id="parameterAllowReserved"></span>allowReserved</td>
<td style="text-align:center"><code>boolean</code></td>
<td>Determines whether the parameter value <em class="rfc2119">SHOULD</em> allow reserved characters, as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <code>:/?#[]@!$&amp;'()*+,;=</code> to be included without percent-encoding. This property only applies to parameters with an <code>in</code> value of <code>query</code>. The default value is <code>false</code>.</td>
<td>Determines whether the parameter value <em class="rfc2119">SHOULD</em> allow reserved characters, as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-2.2">Section 2.2</a> <code>:/?#[]@!$&amp;'()*+,;=</code> to be included without percent-encoding. This property only applies to parameters with an <code>in</code> value of <code>query</code>. The default value is <code>false</code>.</td>
</tr>
<tr>
<td><span id="parameterSchema"></span>schema</td>
Expand Down Expand Up @@ -1543,25 +1543,25 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<td>matrix</td>
<td><code>primitive</code>, <code>array</code>, <code>object</code></td>
<td><code>path</code></td>
<td>Path-style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>]</td>
<td>Path-style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>] <a href="https://tools.ietf.org/html/rfc6570#section-3.2.7">Section 3.2.7</a></td>
</tr>
<tr>
<td>label</td>
<td><code>primitive</code>, <code>array</code>, <code>object</code></td>
<td><code>path</code></td>
<td>Label style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>]</td>
<td>Label style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>] <a href="https://tools.ietf.org/html/rfc6570#section-3.2.5">Section 3.2.5</a></td>
</tr>
<tr>
<td>form</td>
<td><code>primitive</code>, <code>array</code>, <code>object</code></td>
<td><code>query</code>, <code>cookie</code></td>
<td>Form style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>]. This option replaces <code>collectionFormat</code> with a <code>csv</code> (when <code>explode</code> is false) or <code>multi</code> (when <code>explode</code> is true) value from OpenAPI 2.0.</td>
<td>Form style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>] <a href="https://tools.ietf.org/html/rfc6570#section-3.2.8">Section 3.2.8</a>. This option replaces <code>collectionFormat</code> with a <code>csv</code> (when <code>explode</code> is false) or <code>multi</code> (when <code>explode</code> is true) value from OpenAPI 2.0.</td>
</tr>
<tr>
<td>simple</td>
<td><code>array</code></td>
<td><code>path</code>, <code>header</code></td>
<td>Simple style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>]. This option replaces <code>collectionFormat</code> with a <code>csv</code> value from OpenAPI 2.0.</td>
<td>Simple style parameters defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc6570" title="URI Template">RFC6570</a></cite>] <a href="https://tools.ietf.org/html/rfc6570#section-3.2.2">Section 3.2.2</a>. This option replaces <code>collectionFormat</code> with a <code>csv</code> value from OpenAPI 2.0.</td>
</tr>
<tr>
<td>spaceDelimited</td>
Expand Down Expand Up @@ -2138,7 +2138,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<span class="hljs-attr">type:</span> <span class="hljs-string">object</span>
<span class="hljs-attr">properties:</span> {}
</code></pre>
<p>In this example, the contents in the <code>requestBody</code> <em class="rfc2119">MUST</em> be stringified per [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc1866" title="Hypertext Markup Language - 2.0">RFC1866</a></cite>] when passed to the server. In addition, the <code>address</code> field complex object will be stringified.</p>
<p>In this example, the contents in the <code>requestBody</code> <em class="rfc2119">MUST</em> be stringified per <a href="https://tools.ietf.org/html/rfc1866/">[RFC1866]</a> when passed to the server. In addition, the <code>address</code> field complex object will be stringified.</p>
<p>When passing complex objects in the <code>application/x-www-form-urlencoded</code> content type, the default serialization strategy of such properties is described in the <a href="#encoding-object"><code>Encoding Object</code></a>’s <a href="#encodingStyle"><code>style</code></a> property as <code>form</code>.</p>
</section><section id="special-considerations-for-multipart-content"><div class="header-wrapper"><h5 id="x4-7-14-5-special-considerations-for-multipart-content"><bdi class="secno">4.7.14.5 </bdi>Special Considerations for <code>multipart</code> Content</h5><a class="self-link" href="#special-considerations-for-multipart-content" aria-label="Permalink for Section 4.7.14.5"></a></div>
<p>It is common to use <code>multipart/form-data</code> as a <code>Content-Type</code> when transferring request bodies to operations. In contrast to 2.0, a <code>schema</code> is <em class="rfc2119">REQUIRED</em> to define the input parameters to the operation when using <code>multipart</code> content. This supports complex structures as well as supporting mechanisms for multiple file uploads.</p>
Expand Down Expand Up @@ -2214,7 +2214,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<tr>
<td><span id="encodingAllowReserved"></span>allowReserved</td>
<td style="text-align:center"><code>boolean</code></td>
<td>Determines whether the parameter value <em class="rfc2119">SHOULD</em> allow reserved characters, as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <code>:/?#[]@!$&amp;'()*+,;=</code> to be included without percent-encoding. The default value is <code>false</code>. This property <em class="rfc2119">SHALL</em> be ignored if the request body media type is not <code>application/x-www-form-urlencoded</code>.</td>
<td>Determines whether the parameter value <em class="rfc2119">SHOULD</em> allow reserved characters, as defined by [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc3986" title="Uniform Resource Identifier (URI): Generic Syntax">RFC3986</a></cite>] <a href="https://tools.ietf.org/html/rfc3986#section-2.2">Section 2.2</a> <code>:/?#[]@!$&amp;'()*+,;=</code> to be included without percent-encoding. The default value is <code>false</code>. This property <em class="rfc2119">SHALL</em> be ignored if the request body media type is not <code>application/x-www-form-urlencoded</code>.</td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -2362,7 +2362,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<tr>
<td><span id="responseHeaders"></span>headers</td>
<td style="text-align:center">Map[<code>string</code>, <a href="#header-object">Header Object</a> | <a href="#reference-object">Reference Object</a>]</td>
<td>Maps a header name to its definition. [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7230" title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">RFC7230</a></cite>] states header names are case insensitive. If a response header is defined with the name <code>"Content-Type"</code>, it <em class="rfc2119">SHALL</em> be ignored.</td>
<td>Maps a header name to its definition. [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7230" title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">RFC7230</a></cite>] <a href="https://tools.ietf.org/html/rfc7230#page-22">Page 22</a> states header names are case insensitive. If a response header is defined with the name <code>"Content-Type"</code>, it <em class="rfc2119">SHALL</em> be ignored.</td>
</tr>
<tr>
<td><span id="responseContent"></span>content</td>
Expand Down Expand Up @@ -3975,7 +3975,7 @@ <h1 id="title" class="title">OpenAPI Specification v3.0.0 </h1> <h2 id="subtitle
<td><span id="securitySchemeScheme"></span>scheme</td>
<td style="text-align:center"><code>string</code></td>
<td><code>http</code></td>
<td><strong><em class="rfc2119">REQUIRED</em></strong>. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7235" title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">RFC7235</a></cite>].</td>
<td><strong><em class="rfc2119">REQUIRED</em></strong>. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc7235" title="Hypertext Transfer Protocol (HTTP/1.1): Authentication">RFC7235</a></cite>] <a href="https://tools.ietf.org/html/rfc7235#section-5.1">Section 5.1</a>.</td>
</tr>
<tr>
<td><span id="securitySchemeBearerFormat"></span>bearerFormat</td>
Expand Down
Loading

0 comments on commit 4b1c40f

Please sign in to comment.