1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
<!DOCTYPE html><html lang="en"><head>
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-831873-42"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-831873-42');
</script>
<meta charset="UTF-8">
<title>OpenAPI Specification v30.0.1 | Introduction, Definitions, & More</title><meta name="description" content="The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs.">
<meta name="color-scheme" content="light dark"><script src="../js/respec-w3c.js" class="remove"></script><script class="remove">var respecConfig = {"specStatus":"base","latestVersion":"https://spec.openapis.org/oas/latest.html","thisVersion":"https://spec.openapis.org/oas/v30.0.1.html","canonicalURI":"https://spec.openapis.org/oas/v30.0.1.html","editors":[{"name":"John Doe "},{"name":"Jane Doe "}],"formerEditors":[{"name":"Foo Bar "}],"publishDate":"3001-04-01T00:00:00.000Z","subtitle":"Version 30.0.1","edDraftURI":"https://github.com/OAI/OpenAPI-Specification/","shortName":"OAS","historyURI":null,"lint":false,"logos":[{"src":"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png","alt":"OpenAPI Initiative","height":48,"url":"https://openapis.org/"}],"otherLinks":[{"key":"Other versions:","data":[{"href":"https://spec.openapis.org/oas/v31.0.0.html"},{"href":"https://spec.openapis.org/oas/v30.0.0.html"}]},{"key":"Participate","data":[{"value":"GitHub OAI/OpenAPI-Specification","href":"https://github.com/OAI/OpenAPI-Specification/"},{"value":"File a bug","href":"https://github.com/OAI/OpenAPI-Specification/issues"},{"value":"Commit history","href":"https://github.com/OAI/OpenAPI-Specification/commits/main/versions/30.0.1.md"},{"value":"Pull requests","href":"https://github.com/OAI/OpenAPI-Specification/pulls"}]}]};</script>
</head>
<body><style>#respec-ui { visibility: hidden; } #title { color: #578000; } #subtitle { color: #578000; } .dt-published { color: #578000; } .dt-published::before { content: "Published "; } h1, h2, h3, h4, h5, h6 { color: #578000; font-weight: normal; font-style: normal; } a[href] { color: #45512c; } body:not(.toc-inline) #toc h2 { color: #45512c; } table { display: block; width: 100%; overflow: auto; } table th { font-weight: 600; } table th, table td { padding: 6px 13px; border: 1px solid #dfe2e5; } table tr { background-color: #fff; border-top: 1px solid #c6cbd1; } table tr:nth-child(2n) { background-color: #f6f8fa; } pre { background-color: #f6f8fa !important; } code { color: #c83500 } th code { color: inherit } a.bibref { text-decoration: underline; } body.darkmode { --toclink-underline: #6a9000; --toclink-visited-underline: #fff; } body.darkmode a, body.darkmode .tocxref, body.darkmode .u-url { color: #6a9000; } body.darkmode code { color: #e66c33; } body.darkmode:not(.toc-inline) #toc h2, body.darkmode h1, body.darkmode h2, body.darkmode h3, body.darkmode h4, body.darkmode h5, body.darkmode h6, body.darkmode #title, body.darkmode #subtitle, body.darkmode .toc-inline, body.darkmode .dt-published { color: #7bb01c; } body.darkmode pre, body.darkmode table tr:nth-child(2n), body.darkmode table tr { background-color: #1e1e1e !important; color: #dcdcdc; } body.darkmode img { background: transparent; } body.darkmode .logo img { display: none; } body.darkmode .logo::before { content: ""; display: inline-block; height: 48px; width: 175px; background: url("https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/refs/heads/main/graphics/bitmap/OpenAPI_Logo_Pantone.png") no-repeat center / contain; vertical-align: middle; } /** This contains the content of the https://www.w3.org/StyleSheets/TR/2021/dark.css file */ body.darkmode { --text: #ddd; --bg: black; /* Absolute URLs due to https://bugs.webkit.org/show_bug.cgi?id=230243 */ --unofficial-watermark: url(https://www.w3.org/StyleSheets/TR/2021/logos/UD-watermark-dark-unofficial); --draft-watermark: url(https://www.w3.org/StyleSheets/TR/2021/logos/UD-watermark-dark-draft); --logo-bg: #1a5e9a; --logo-active-bg: #c00; --logo-text: white; --tocnav-normal-text: #999; --tocnav-normal-bg: var(--bg); --tocnav-hover-text: var(--tocnav-normal-text); --tocnav-hover-bg: #080808; --tocnav-active-text: #f44; --tocnav-active-bg: var(--tocnav-normal-bg); --tocsidebar-text: var(--text); --tocsidebar-bg: #080808; --tocsidebar-shadow: rgba(255,255,255,.1); --tocsidebar-heading-text: hsla(203,20%,40%,.7); --toclink-text: var(--text); --toclink-underline: #6af; --toclink-visited-text: var(--toclink-text); --toclink-visited-underline: #054572; --heading-text: #8af; --hr-text: var(--text); --algo-border: #456; --del-text: #f44; --del-bg: transparent; --ins-text: #4a4; --ins-bg: transparent; --a-normal-text: #6af; --a-normal-underline: #555; --a-visited-text: var(--a-normal-text); --a-visited-underline: var(--a-normal-underline); --a-hover-bg: rgba(25%, 25%, 25%, .2); --a-active-text: #f44; --a-active-underline: var(--a-active-text); --borderedblock-bg: rgba(255, 255, 255, .05); --blockquote-border: silver; --blockquote-bg: var(--borderedblock-bg); --blockquote-text: currentcolor; --issue-border: #e05252; --issue-bg: var(--borderedblock-bg); --issue-text: var(--text); --issueheading-text: hsl(0deg, 70%, 70%); --example-border: hsl(50deg, 90%, 60%); --example-bg: var(--borderedblock-bg); --example-text: var(--text); --exampleheading-text: hsl(50deg, 70%, 70%); --note-border: hsl(120deg, 100%, 35%); --note-bg: var(--borderedblock-bg); --note-text: var(--text); --noteheading-text: hsl(120, 70%, 70%); --notesummary-underline: silver; --advisement-border: orange; --advisement-bg: #222218; --advisement-text: var(--text); --advisementheading-text: #f84; --amendment-border: #330099; --amendment-bg: var(--borderedblock-bg); --amendment-text: var(--text); --amendmentheading-text: #a086ff; --amendment-border: #330099; --amendment-bg: #080010; --amendment-text: var(--text); --amendmentheading-text: #cc00ff; --warning-border: red; --warning-bg: hsla(40,100%,20%,0.95); --warning-text: var(--text); --def-border: #8ccbf2; --def-bg: #080818; --def-text: var(--text); --defrow-border: #136; --datacell-border: silver; --indexinfo-text: #aaa; --indextable-hover-text: var(--text); --indextable-hover-bg: #181818; --outdatedspec-bg: rgba(255, 255, 255, .5); --outdatedspec-text: black; --outdated-bg: maroon; --outdated-text: white; --outdated-shadow: red; --editedrec-bg: darkorange; }/** * GitHub Gist Theme * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro */ .hljs { display: block; background: white; padding: 0.5em; color: #333333; overflow-x: auto; } .hljs-comment, .hljs-meta { color: #727070; } .hljs-string, .hljs-variable, .hljs-template-variable, .hljs-strong, .hljs-emphasis, .hljs-quote { color: #c74700; } .hljs-number { color: #005e5e; } .hljs-keyword, .hljs-selector-tag, .hljs-type { color: #a71d5d; } .hljs-literal, .hljs-symbol, .hljs-bullet, .hljs-attribute { color: #007aa2; } .hljs-section, .hljs-name { color: #4b7c46; } .hljs-tag { color: #333333; } .hljs-title, .hljs-attr, .hljs-selector-id, .hljs-selector-class, .hljs-selector-attr, .hljs-selector-pseudo { color: #795da3; } .hljs-addition { color: #55a532; background-color: #eaffea; } .hljs-deletion { color: #bd2c00; background-color: #ffecec; } .hljs-link { text-decoration: underline; } </style><h1 id="title">OpenAPI Specification v30.0.1 </h1><p class="copyright">Copyright © 3001 the Linux Foundation</p><section class="notoc" id="abstract"><h2>What is the OpenAPI Specification?</h2>The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.</section><section class="override" id="sotd" data-max-toc="0"><h2>Status of This Document</h2>The source-of-truth for this specification is the HTML file referenced above as <em>This version</em>.</section>
<section><h1>Heading 1</h1>
<p>Text for first chapter</p>
<section class="override" id="conformance"><h2>Version 30.0.1</h2>
<p>This is the conformance section</p>
</section></section><section><h1>Heading 2</h1>
<p>Text for <span id="first-anchor"></span>first section</p>
</section><section><h1><dfn>Definitions</dfn></h1>
<section><h2><dfn>Foo</dfn></h2>
<p>Definition of Foo.</p>
</section></section><section><h1>Another Heading 2</h1>
<p>Text for second section</p>
<p><a href="https://learn.openapis.org/examples/foo.html">Relative link to example</a></p>
<p><a href="https://github.com/OAI/OpenAPI-Specification/tree/main/something/else">Relative link to something else</a></p>
<section><h2>Heading 3</h2>
<p>Text for first subsection</p>
<p>[[RFC3986]]</p>
<p>[[RFC9110]] <a href="https://datatracker.ietf.org/doc/html/rfc9110#section-4">Section 4</a></p>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-punctuation">{</span>
<span class="hljs-attr">"foo"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span>
<span class="hljs-punctuation">}</span>
</code></pre>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-attr">foo:</span> <span class="hljs-literal">true</span>
</code></pre>
<pre class="nohighlight" tabindex="0"><code>text/plain
</code></pre>
<pre class="nohighlight" tabindex="0"><code>no language
</code></pre>
<pre class="nohighlight" tabindex="0"><code>unknown language
</code></pre>
<pre class="nohighlight" tabindex="0"><code>https://<span class="hljs-attr">foo.com</span>/<span class="hljs-attr">bar</span>?<span class="hljs-attr">baz</span>=<span class="hljs-literal">qux</span>&<span class="hljs-attr">fred</span>=<span class="hljs-literal">waldo</span>#<span class="hljs-attr">fragment</span>
</code></pre>
<pre class="nohighlight" tabindex="0"><code>https://foo.com/bar{<span class="hljs-attr">?baz*</span>,<span class="hljs-attr">qux</span>}
</code></pre>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-meta">--boundary-example</span>
<span class="hljs-literal">Content-Type:<span class="hljs-attr"> application/openapi+yaml</span></span>
<span class="hljs-literal">Content-Location:<span class="hljs-attr"> https://inaccessible-domain.com/api/openapi.yaml</span></span>
openapi: 3.2.0
info:
title: Example API
version: 1.0
externalDocs:
url: docs.html
<span class="hljs-meta">--boundary-example</span>
<span class="hljs-literal">Content-Type:<span class="hljs-attr"> text/html</span></span>
<span class="hljs-literal">Content-Location:<span class="hljs-attr"> https://example.com/api/docs.html</span></span>
<html>
<head>
<title>API Documentation</title>
</head>
<body>
<p>Awesome documentation goes here</p>
</body>
</html>
</code></pre>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-attr">event</span>: addString
<span class="hljs-attr">data</span>: This data is formatted
<span class="hljs-attr">data</span>: across two lines
<span class="hljs-attr">retry</span>: 5
<span class="hljs-attr">
event</span>: addNumber
<span class="hljs-attr">data</span>: 1234.5678
<span class="hljs-attr">unknownField</span>: this is ignored
<span class="hljs-attr">
</span><span class="hljs-comment">: This is a comment</span>
<span class="hljs-attr">event</span>: addJSON
<span class="hljs-attr">data</span>: {"foo": 42}
</code></pre>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-punctuation">{</span><span class="hljs-attr">"event"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"addString"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"This data is formatted\nacross two lines"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"retry"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">5</span><span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">{</span><span class="hljs-attr">"event"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"addNumber"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1234.5678"</span><span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">{</span><span class="hljs-attr">"event"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"addJSON"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{\"foo\": 42}"</span><span class="hljs-punctuation">}</span>
</code></pre>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-punctuation">{</span><span class="hljs-attr">"event"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"addString"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"This data is formatted\nacross two lines"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"retry"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">5</span><span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">{</span><span class="hljs-attr">"event"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"addNumber"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1234.5678"</span><span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">{</span><span class="hljs-attr">"event"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"addJSON"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"data"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"{\"foo\": 42}"</span><span class="hljs-punctuation">}</span>
</code></pre>
<pre class="nohighlight" tabindex="0"><code><span class="hljs-meta">0x1E</span><span class="hljs-punctuation">{</span>
<span class="hljs-attr">"timestamp"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1985-04-12T23:20:50.52Z"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"level"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Hi!"</span>
<span class="hljs-punctuation">}</span>
<span class="hljs-meta">0x1E</span><span class="hljs-punctuation">{</span>
<span class="hljs-attr">"timestamp"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"1985-04-12T23:20:51.37Z"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"level"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Bye!"</span>
<span class="hljs-punctuation">}</span>
</code></pre>
</section></section><section class="appendix"><h1>Appendix A: Revision History</h1>
<table>
<thead>
<tr>
<th>Version</th>
<th>Date</th>
</tr>
</thead>
<tbody>
<tr>
<td>30.0.1</td>
<td>3001-04-01</td>
</tr>
</tbody>
</table>
|
