Deploy to GitHub pages
This commit is contained in:
github-actions[bot]
GitHub
commit
1287bbd06a
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1,76 @@
|
|||
import{_ as n,c as s,o as a,a as t}from"./app.3ef9e972.js";const q='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"Doctrine","slug":"doctrine"},{"level":2,"title":"Escaping","slug":"escaping"},{"level":2,"title":"Arrays and Objects","slug":"arrays-and-objects"},{"level":2,"title":"Constants","slug":"constants"}],"relativePath":"guide/annotations.md"}',o={},e=t(`<h1 id="annotations" tabindex="-1">Annotations <a class="header-anchor" href="#annotations" aria-hidden="true">#</a></h1><div class="tip custom-block"><p class="custom-block-title">Namespace</p><p>Using a namespace alias simplifies typing and improves readability.</p><p>All annotations are in the <code>OpenApi\\Annotations</code> namespace.</p></div><p>Since Annotations are technically PHP comments, adding <code>use OpenApi\\Annotations as OA;</code> is strictly speaking not necessary. However, doctrine will be quite specific about whether an alias is valid or not.</p><p><code>swagger-php</code> will automatically register the <code>@OA</code> alias so all annotations can be used using the <code>@OA</code> shortcut without any additional work.</p><h2 id="doctrine" tabindex="-1">Doctrine <a class="header-anchor" href="#doctrine" aria-hidden="true">#</a></h2><p>Annotations are PHP comments (docblocks) containing <a href="https://www.doctrine-project.org/projects/annotations.html" target="_blank" rel="noopener noreferrer">doctrine style annotations</a>.</p><div class="info custom-block"><p class="custom-block-title">INFO</p><p>All documentation related to doctrine applies to annotations only.</p></div><p><strong>Example:</strong></p><div class="language-php"><pre><code><span class="token php language-php"><span class="token delimiter important"><?php</span>
|
||||
|
||||
<span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Annotations</span> <span class="token keyword">as</span> <span class="token constant">OA</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @OA\\Info(title="My First API", version="0.1")
|
||||
*/</span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">OpenApi</span> <span class="token punctuation">{</span><span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">MyController</span> <span class="token punctuation">{</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @OA\\Get(
|
||||
* path="/api/resource.json",
|
||||
* @OA\\Response(response="200", description="An example resource")
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">resource</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">// ...</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</span></code></pre></div><h2 id="escaping" tabindex="-1">Escaping <a class="header-anchor" href="#escaping" aria-hidden="true">#</a></h2><div class="tip custom-block"><p class="custom-block-title">Escaping double quotes</p><p>Double quotes can be escaped by doubling them rather than using <code>\\</code></p><p>For example:</p><div class="language-php"><pre><code> @<span class="token constant">OA</span><span class="token function"><span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span>
|
||||
title<span class="token operator">=</span><span class="token string double-quoted-string">"Request"</span><span class="token punctuation">,</span>
|
||||
schema<span class="token operator">=</span><span class="token string double-quoted-string">"Request"</span><span class="token punctuation">,</span>
|
||||
example<span class="token operator">=</span><span class="token punctuation">{</span>
|
||||
<span class="token string double-quoted-string">"configuration"</span><span class="token punctuation">:</span><span class="token string double-quoted-string">"{"</span><span class="token string double-quoted-string">"formConfig"</span><span class="token string double-quoted-string">":123}"</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">)</span>
|
||||
</code></pre></div></div><h2 id="arrays-and-objects" tabindex="-1">Arrays and Objects <a class="header-anchor" href="#arrays-and-objects" aria-hidden="true">#</a></h2><p>Doctrine annotations support arrays, but use <code>{</code> and <code>}</code> instead of <code>[</code> and <code>]</code>.</p><p>Doctrine also supports objects, which also use <code>{</code> and <code>}</code> and require the property names to be surrounded with <code>"</code>.</p><div class="warning custom-block"><p class="custom-block-title">DON'T WRITE</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Info(
|
||||
* title="My first API",
|
||||
* version="1.0.0",
|
||||
* contact={
|
||||
* "email": "support@example.com"
|
||||
* }
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div></div><p>This "works" but most objects have an annotation with the same name as the property, such as <code>@OA\\Contact</code> for <code>contact</code>:</p><div class="tip custom-block"><p class="custom-block-title">WRITE</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Info(
|
||||
* title="My first API",
|
||||
* version="1.0.0",
|
||||
* @OA\\Contact(
|
||||
* email="support@example.com"
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div></div><p>This also adds validation, so when you misspell a property or forget a required property, it will trigger a PHP warning.</p><p>For example, if you write <code>emial="support@example.com"</code>, swagger-php would generate a notice with <code>Unexpected field "emial" for @OA\\Contact(), expecting "name", "email", ...</code></p><p>Placing multiple annotations of the same type will result in an array of objects. For objects, the key is defined by the field with the same name as the annotation: <code>response</code> in a <code>@OA\\Response</code>, <code>property</code> in a <code>@OA\\Property</code>, etc.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Get(
|
||||
* path="/products",
|
||||
* summary="list products",
|
||||
* @OA\\Response(
|
||||
* response=200,
|
||||
* description="A list with products"
|
||||
* ),
|
||||
* @OA\\Response(
|
||||
* response="default",
|
||||
* description="an ""unexpected"" error"
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p><strong>Results in</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">paths</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">/products</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">get</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">summary</span><span class="token punctuation">:</span> <span class="token string">"list products"</span>
|
||||
<span class="token key atrule">responses</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">"200"</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">"A list with products"</span>
|
||||
<span class="token key atrule">default</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">'an "unexpected" error'</span>
|
||||
</code></pre></div><h2 id="constants" tabindex="-1">Constants <a class="header-anchor" href="#constants" aria-hidden="true">#</a></h2><p>You can use constants inside doctrine annotations.</p><div class="language-php"><pre><code><span class="token function">define</span><span class="token punctuation">(</span><span class="token string double-quoted-string">"API_HOST"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token variable">$env</span> <span class="token operator">===</span> <span class="token string double-quoted-string">"production"</span><span class="token punctuation">)</span> <span class="token operator">?</span> <span class="token string double-quoted-string">"example.com"</span> <span class="token punctuation">:</span> <span class="token string double-quoted-string">"localhost"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</code></pre></div><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Server(url=API_HOST)
|
||||
*/</span>
|
||||
</code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Using the CLI you might need to include the php file with the constants using the <code>--bootstrap</code> options.</p><div class="language-shell"><pre><code><span class="token operator">></span> openapi <span class="token parameter variable">--bootstrap</span> constants.php
|
||||
</code></pre></div></div>`,28),p=[e];function c(i,l,u,r,d,k){return a(),s("div",null,p)}var g=n(o,[["render",c]]);export{q as __pageData,g as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as n,c as s,o as a,a as t}from"./app.3ef9e972.js";const q='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"Doctrine","slug":"doctrine"},{"level":2,"title":"Escaping","slug":"escaping"},{"level":2,"title":"Arrays and Objects","slug":"arrays-and-objects"},{"level":2,"title":"Constants","slug":"constants"}],"relativePath":"guide/annotations.md"}',o={},e=t("",28),p=[e];function c(i,l,u,r,d,k){return a(),s("div",null,p)}var g=n(o,[["render",c]]);export{q as __pageData,g as default};
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
import{_ as s,c as n,o as a,a as t}from"./app.3ef9e972.js";const b='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"Nesting","slug":"nesting"}],"relativePath":"guide/attributes.md"}',e={},p=t(`<h1 id="attributes" tabindex="-1">Attributes <a class="header-anchor" href="#attributes" aria-hidden="true">#</a></h1><div class="tip custom-block"><p class="custom-block-title">Namespace</p><p>Using a namespace alias simplifies typing and improves readability.</p><p>All attributes are in the <code>OpenApi\\Attributes</code> namespace.</p></div><h2 id="nesting" tabindex="-1">Nesting <a class="header-anchor" href="#nesting" aria-hidden="true">#</a></h2><p>Similar to annotations attributes can be top level or nested. However, attributes <strong>may be put at the same level</strong> if there is no ambiguity. <code>swagger-php</code> will then merge attributes according to the defined rules about parent/child relationships.</p><p><strong>Example</strong></p><p>Nested:</p><div class="language-php"><pre><code> <span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Get</span><span class="token punctuation">(</span>
|
||||
<span class="token attribute-class-name class-name">path</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'/api/users'</span><span class="token punctuation">,</span>
|
||||
<span class="token attribute-class-name class-name">responses</span><span class="token punctuation">:</span> <span class="token punctuation">[</span>
|
||||
<span class="token attribute-class-name class-name">new</span> <span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Response</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">response</span><span class="token punctuation">:</span> <span class="token number">200</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">description</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'AOK'</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
|
||||
<span class="token attribute-class-name class-name">new</span> <span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Response</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">response</span><span class="token punctuation">:</span> <span class="token number">401</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">description</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'Not allowed'</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
|
||||
<span class="token punctuation">]</span>
|
||||
<span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">users</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token comment">/* ... */</span> <span class="token punctuation">}</span>
|
||||
</code></pre></div><p>Not nested:</p><div class="language-php"><pre><code> <span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Get</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">path</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'/api/users'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Response</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">response</span><span class="token punctuation">:</span> <span class="token number">200</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">description</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'AOK'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Response</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">response</span><span class="token punctuation">:</span> <span class="token number">401</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">description</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'Not allowed'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">users</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token comment">/* ... */</span> <span class="token punctuation">}</span>
|
||||
</code></pre></div><p>Depending on how much nesting there is this can make things a bit simpler and easier to read.</p><div class="warning custom-block"><p class="custom-block-title">Top level only</p><p>Automatic merging of attributes works only at the top level - in the example that would be the method <code>users()</code>.</p></div>`,11),c=[p];function o(i,l,u,r,k,m){return a(),n("div",null,c)}var g=s(e,[["render",o]]);export{b as __pageData,g as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as s,c as n,o as a,a as t}from"./app.3ef9e972.js";const b='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"Nesting","slug":"nesting"}],"relativePath":"guide/attributes.md"}',e={},p=t("",11),c=[p];function o(i,l,u,r,k,m){return a(),n("div",null,c)}var g=s(e,[["render",o]]);export{b as __pageData,g as default};
|
||||
|
|
@ -0,0 +1,216 @@
|
|||
import{_ as n,c as s,o as a,a as e}from"./app.3ef9e972.js";const h='{"title":"Common techniques","description":"","frontmatter":{},"headers":[{"level":2,"title":"Annotation placement","slug":"annotation-placement"},{"level":2,"title":"Context awareness","slug":"context-awareness"},{"level":2,"title":"Response media type","slug":"response-media-type"},{"level":2,"title":"Using references - $ref","slug":"using-references-ref"},{"level":2,"title":"Array parameters in query","slug":"array-parameters-in-query"},{"level":2,"title":"Vendor extensions","slug":"vendor-extensions"},{"level":2,"title":"Enums","slug":"enums"},{"level":3,"title":"Enum cases as value","slug":"enum-cases-as-value"},{"level":2,"title":"Enum schemas","slug":"enum-schemas"}],"relativePath":"guide/common-techniques.md"}',t={},p=e(`<h1 id="common-techniques" tabindex="-1">Common techniques <a class="header-anchor" href="#common-techniques" aria-hidden="true">#</a></h1><h2 id="annotation-placement" tabindex="-1">Annotation placement <a class="header-anchor" href="#annotation-placement" aria-hidden="true">#</a></h2><p>You shouldn't place all annotations inside one big block, but scatter them throughout your codebase as close to the relevant source code as appropriate.</p><p><code>swagger-php</code> will scan your project and merge all meta-data into one<code> @OA\\OpenApi</code> annotation.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>As of <code>swagger-php</code> v4 all annotations or attributes must be associated with a structural element (<code>class</code>, <code>method</code>, <code>parameter</code> or <code>enum</code>)</p></div><h2 id="context-awareness" tabindex="-1">Context awareness <a class="header-anchor" href="#context-awareness" aria-hidden="true">#</a></h2><p><code>swagger-php</code> looks at the context of the annotation and will augment it with things like <code>property name</code>, <code>data type</code> (doctype and native type hints) as well as a couple other things.</p><p>This means in a lot of cases it is not necessary to explicitly document all details.</p><p><strong>Example</strong></p><div class="language-php"><pre><code><span class="token php language-php"><span class="token delimiter important"><?php</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @OA\\Schema()
|
||||
*/</span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Product</span> <span class="token punctuation">{</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* The product name,
|
||||
* @var string
|
||||
* @OA\\Property()
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token variable">$name</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</span></code></pre></div><p><strong>Results in</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Product</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">name</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">"The product name"</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
</code></pre></div><p><strong>As if you'd written</strong></p><div class="language-php"><pre><code> <span class="token comment">/**
|
||||
* The product name
|
||||
* @var string
|
||||
*
|
||||
* @OA\\Property(
|
||||
* property="name",
|
||||
* type="string",
|
||||
* description="The product name"
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token variable">$name</span><span class="token punctuation">;</span>
|
||||
</code></pre></div><h2 id="response-media-type" tabindex="-1">Response media type <a class="header-anchor" href="#response-media-type" aria-hidden="true">#</a></h2><p>The <code>@OA\\MediaType</code> is used to describe the content:</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Response(
|
||||
* response=200,
|
||||
* description="successful operation",
|
||||
* @OA\\MediaType(
|
||||
* mediaType="application/json",
|
||||
* @OA\\Schema(ref="#/components/schemas/User"),
|
||||
* )
|
||||
* ),
|
||||
*/</span>
|
||||
</code></pre></div><p>But because most API requests and responses are JSON, the <code>@OA\\JsonContent</code> allows you to simplify this by writing:</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Response(
|
||||
* response=200,
|
||||
* description="successful operation",
|
||||
* @OA\\JsonContent(ref="#/components/schemas/User"),
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p>During processing the <code>@OA\\JsonContent</code> unfolds to <code>@OA\\MediaType( mediaType="application/json", @OA\\Schema(...)</code> and will generate the same output.</p><h2 id="using-references-ref" tabindex="-1">Using references - <code>$ref</code> <a class="header-anchor" href="#using-references-ref" aria-hidden="true">#</a></h2><p>It's quite common that endpoints have some overlap in either their request or response data. To keep things DRY (Don't Repeat Yourself) the specification allows reusing components using <code>$ref</code>'s</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Schema(
|
||||
* schema="product_id",
|
||||
* type="integer",
|
||||
* format="int64",
|
||||
* description="The unique identifier of a product in our catalog"
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p><strong>Results in:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">product_id</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">"The unique identifier of a product in our catalog"</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> integer
|
||||
<span class="token key atrule">format</span><span class="token punctuation">:</span> int64
|
||||
</code></pre></div><p>This doesn't do anything by itself, but now you can reference this fragment by its path in the document tree <code>#/components/schemas/product_id</code></p><div class="language-php"><pre><code> <span class="token comment">/**
|
||||
* @OA\\Property(ref="#/components/schemas/product_id")
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token variable">$id</span><span class="token punctuation">;</span>
|
||||
</code></pre></div><div class="info custom-block"><p class="custom-block-title">Examples</p><p>There are more uses cases on how to use refs in the <a href="https://github.com/zircote/swagger-php/tree/master/Examples/using-refs" target="_blank" rel="noopener noreferrer">using-refs example</a>.</p></div><h2 id="array-parameters-in-query" tabindex="-1">Array parameters in query <a class="header-anchor" href="#array-parameters-in-query" aria-hidden="true">#</a></h2><p>Depending on <a href="https://swagger.io/specification/#style-values" target="_blank" rel="noopener noreferrer">style-values</a> <code>@OA\\Parameter(in="query", name="param", ...)</code> might create urls like this: <code>path?param=123&param=abc</code> which do not work when reading the param values in PHP.</p><p>The solution is to change the name <code>param</code> into <code>param[]</code> which will create <code>path?param[]=123&param[]=abc</code> and results in a PHP array.</p><h2 id="vendor-extensions" tabindex="-1">Vendor extensions <a class="header-anchor" href="#vendor-extensions" aria-hidden="true">#</a></h2><p>The specification allows for <a href="http://swagger.io/specification/#vendorExtensions" target="_blank" rel="noopener noreferrer">custom properties</a> as long as they start with "x-". Therefore, all swagger-php annotations have an <code>x</code> property which accepts an array (map) and will unfold into "x-" properties.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Info(
|
||||
* title="Example",
|
||||
* version="1.0.0",
|
||||
* x={
|
||||
* "some-name": "a-value",
|
||||
* "another": 2,
|
||||
* "complex-type": {
|
||||
* "supported":{
|
||||
* {"version": "1.0", "level": "baseapi"},
|
||||
* {"version": "2.1", "level": "fullapi"},
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p><strong>Results in:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">info</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">title</span><span class="token punctuation">:</span> Example
|
||||
<span class="token key atrule">version</span><span class="token punctuation">:</span> <span class="token number">1</span>
|
||||
<span class="token key atrule">x-some-name</span><span class="token punctuation">:</span> a<span class="token punctuation">-</span>value
|
||||
<span class="token key atrule">x-another</span><span class="token punctuation">:</span> <span class="token number">2</span>
|
||||
<span class="token key atrule">x-complex-type</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">supported</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> <span class="token key atrule">version</span><span class="token punctuation">:</span> <span class="token string">"1.0"</span>
|
||||
<span class="token key atrule">level</span><span class="token punctuation">:</span> baseapi
|
||||
<span class="token punctuation">-</span> <span class="token key atrule">version</span><span class="token punctuation">:</span> <span class="token string">"2.1"</span>
|
||||
<span class="token key atrule">level</span><span class="token punctuation">:</span> fullapi
|
||||
</code></pre></div><h2 id="enums" tabindex="-1">Enums <a class="header-anchor" href="#enums" aria-hidden="true">#</a></h2><p><a href="https://www.php.net/manual/en/language.enumerations.basics.php" target="_blank" rel="noopener noreferrer">PHP 8.1 enums</a> are supported in two main use cases.</p><h3 id="enum-cases-as-value" tabindex="-1">Enum cases as value <a class="header-anchor" href="#enum-cases-as-value" aria-hidden="true">#</a></h3><p>Enum cases can be used as value in an <code>enum</code> list just like a <code>string</code>, <code>integer</code> or any other primitive type.</p><p><strong>Basic enum:</strong></p><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OAT</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">enum</span> <span class="token class-name-definition class-name">Suit</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">Hearts</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">Diamonds</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">Clubs</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">Spades</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Model</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">enum</span><span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token attribute-class-name class-name">Suit</span><span class="token operator">::</span><span class="token constant">Hearts</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">Suit</span><span class="token operator">::</span><span class="token constant">Diamonds</span><span class="token punctuation">]</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">protected</span> <span class="token keyword type-declaration">array</span> <span class="token variable">$someSuits</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p><strong>Results in:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Model</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">someSuits</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> array
|
||||
<span class="token key atrule">enum</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> Hearts
|
||||
<span class="token punctuation">-</span> Diamonds
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
|
||||
</code></pre></div><p><strong>Backed enums</strong></p><p>If the enum is a backed enum, the case backing value is used instead of the name.</p><h2 id="enum-schemas" tabindex="-1">Enum schemas <a class="header-anchor" href="#enum-schemas" aria-hidden="true">#</a></h2><p>The simples way of using enums is to annotate them as <code>Schema</code>. This allows you to reference them like any other schema in your spec.</p><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OAT</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">enum</span> <span class="token class-name-definition class-name">Colour</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">GREEN</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">BLUE</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">RED</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Product</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token class-name type-declaration">Colour</span> <span class="token variable">$colour</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p><strong>Results in:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Colour</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">enum</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> GREEN
|
||||
<span class="token punctuation">-</span> BLUE
|
||||
<span class="token punctuation">-</span> RED
|
||||
<span class="token key atrule">Product</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">colour</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/Colour'</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
</code></pre></div><p><strong>Backed enums</strong></p><p>For backed enums there exist two rules that determine whether the name or backing value is used:</p><ol><li>If no schema type is given, the enum name is used.</li><li>If a schema type is given, and it matches the backing type, the enum backing value is used.</li></ol><p><strong>Using the name of a backed enum:</strong></p><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OAT</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">enum</span> <span class="token class-name-definition class-name">Colour</span><span class="token punctuation">:</span> <span class="token keyword type-declaration">int</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">GREEN</span> <span class="token operator">=</span> <span class="token number">1</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">BLUE</span> <span class="token operator">=</span> <span class="token number">2</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">RED</span> <span class="token operator">=</span> <span class="token number">3</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Product</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token class-name type-declaration">Colour</span> <span class="token variable">$colour</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p><strong>Results in:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Colour</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">enum</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> GREEN
|
||||
<span class="token punctuation">-</span> BLUE
|
||||
<span class="token punctuation">-</span> RED
|
||||
<span class="token key atrule">Product</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">colour</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/Colour'</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
</code></pre></div><p><strong>Using the backing value:</strong></p><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OAT</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">type</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'integer'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">enum</span> <span class="token class-name-definition class-name">Colour</span><span class="token punctuation">:</span> <span class="token keyword type-declaration">int</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">GREEN</span> <span class="token operator">=</span> <span class="token number">1</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">BLUE</span> <span class="token operator">=</span> <span class="token number">2</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">RED</span> <span class="token operator">=</span> <span class="token number">3</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Product</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token class-name type-declaration">Colour</span> <span class="token variable">$colour</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p><strong>Results in:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Colour</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> integer
|
||||
<span class="token key atrule">enum</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> <span class="token number">1</span>
|
||||
<span class="token punctuation">-</span> <span class="token number">2</span>
|
||||
<span class="token punctuation">-</span> <span class="token number">3</span>
|
||||
<span class="token key atrule">Product</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">colour</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/Colour'</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
</code></pre></div>`,62),o=[p];function c(l,u,i,r,k,d){return a(),s("div",null,o)}var y=n(t,[["render",c]]);export{h as __pageData,y as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as n,c as s,o as a,a as e}from"./app.3ef9e972.js";const h='{"title":"Common techniques","description":"","frontmatter":{},"headers":[{"level":2,"title":"Annotation placement","slug":"annotation-placement"},{"level":2,"title":"Context awareness","slug":"context-awareness"},{"level":2,"title":"Response media type","slug":"response-media-type"},{"level":2,"title":"Using references - $ref","slug":"using-references-ref"},{"level":2,"title":"Array parameters in query","slug":"array-parameters-in-query"},{"level":2,"title":"Vendor extensions","slug":"vendor-extensions"},{"level":2,"title":"Enums","slug":"enums"},{"level":3,"title":"Enum cases as value","slug":"enum-cases-as-value"},{"level":2,"title":"Enum schemas","slug":"enum-schemas"}],"relativePath":"guide/common-techniques.md"}',t={},p=e("",62),o=[p];function c(l,u,i,r,k,d){return a(),s("div",null,o)}var y=n(t,[["render",c]]);export{h as __pageData,y as default};
|
||||
|
|
@ -0,0 +1,496 @@
|
|||
import{_ as o,c as p,b as c,w as a,a as e,r as u,o as l,d as n,e as s}from"./app.3ef9e972.js";const O='{"title":"Cookbook","description":"","frontmatter":{},"headers":[{"level":2,"title":"x-tagGroups","slug":"x-taggroups"},{"level":2,"title":"Adding examples to @OA\\\\Response","slug":"adding-examples-to-oa-response"},{"level":2,"title":"External documentation","slug":"external-documentation"},{"level":2,"title":"Properties with union types","slug":"properties-with-union-types"},{"level":2,"title":"Referencing a security scheme","slug":"referencing-a-security-scheme"},{"level":2,"title":"File upload with headers","slug":"file-upload-with-headers"},{"level":2,"title":"Set the XML root name","slug":"set-the-xml-root-name"},{"level":2,"title":"upload multipart/form-data","slug":"upload-multipart-form-data"},{"level":2,"title":"Default security scheme for all endpoints","slug":"default-security-scheme-for-all-endpoints"},{"level":2,"title":"Nested objects","slug":"nested-objects"},{"level":2,"title":"Documenting union type response data using oneOf","slug":"documenting-union-type-response-data-using-oneof"},{"level":2,"title":"Reusing responses","slug":"reusing-responses"},{"level":2,"title":"mediaType=\\"/\\"","slug":"mediatype"},{"level":2,"title":"Warning about Multiple response with same response=\\"200\\"","slug":"warning-about-multiple-response-with-same-response-200"},{"level":2,"title":"Callbacks","slug":"callbacks"},{"level":2,"title":"(Mostly) virtual models","slug":"mostly-virtual-models"},{"level":2,"title":"Using class name as type instead of references","slug":"using-class-name-as-type-instead-of-references"},{"level":2,"title":"Enums","slug":"enums"},{"level":2,"title":"Multi value query parameter: &q[]=1&q[]=1","slug":"multi-value-query-parameter-q-1-q-1"},{"level":2,"title":"Custom response classes","slug":"custom-response-classes"},{"level":2,"title":"Annotating class constants","slug":"annotating-class-constants"}],"relativePath":"guide/cookbook.md"}',i={},r=e(`<h1 id="cookbook" tabindex="-1">Cookbook <a class="header-anchor" href="#cookbook" aria-hidden="true">#</a></h1><h2 id="x-taggroups" tabindex="-1"><code>x-tagGroups</code> <a class="header-anchor" href="#x-taggroups" aria-hidden="true">#</a></h2><p>OpenApi has the concept of grouping endpoints using tags. On top of that, some tools (<a href="https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/" target="_blank" rel="noopener noreferrer">redocly</a>, for example) support further grouping via the vendor extension <code>x-tagGroups</code>.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\OpenApi(
|
||||
* x={
|
||||
* "tagGroups"=
|
||||
* {{"name"="User Management", "tags"={"Users", "API keys", "Admin"}}
|
||||
* }
|
||||
* }
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="adding-examples-to-oa-response" tabindex="-1">Adding examples to <code>@OA\\Response</code> <a class="header-anchor" href="#adding-examples-to-oa-response" aria-hidden="true">#</a></h2><div class="language-php"><pre><code><span class="token comment">/*
|
||||
* @OA\\Response(
|
||||
* response=200,
|
||||
* description="OK",
|
||||
* @OA\\JsonContent(
|
||||
* oneOf={
|
||||
* @OA\\Schema(ref="#/components/schemas/Result"),
|
||||
* @OA\\Schema(type="boolean")
|
||||
* },
|
||||
* @OA\\Examples(example="result", value={"success": true}, summary="An result object."),
|
||||
* @OA\\Examples(example="bool", value=false, summary="A boolean value."),
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="external-documentation" tabindex="-1">External documentation <a class="header-anchor" href="#external-documentation" aria-hidden="true">#</a></h2><p>OpenApi allows a single reference to external documentation. This is a part of the top level <code>@OA\\OpenApi</code>.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\OpenApi(
|
||||
* @OA\\ExternalDocumentation(
|
||||
* description="More documentation here...",
|
||||
* url="https://example.com/externaldoc1/"
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>If no <code>@OA\\OpenApi</code> is configured, <code>swagger-php</code> will create one automatically.</p><p>That means the above example would also work with just the <code>OA\\ExternalDocumentation</code> annotation.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\ExternalDocumentation(
|
||||
* description="More documentation here...",
|
||||
* url="https://example.com/externaldoc1/"
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div></div><h2 id="properties-with-union-types" tabindex="-1">Properties with union types <a class="header-anchor" href="#properties-with-union-types" aria-hidden="true">#</a></h2><p>Sometimes properties or even lists (arrays) may contain data of different types. This can be expressed using <code>oneOf</code>.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Schema(
|
||||
* schema="StringList",
|
||||
* @OA\\Property(property="value", type="array", @OA\\Items(anyOf={@OA\\Schema(type="string")}))
|
||||
* )
|
||||
* @OA\\Schema(
|
||||
* schema="String",
|
||||
* @OA\\Property(property="value", type="string")
|
||||
* )
|
||||
* @OA\\Schema(
|
||||
* schema="Object",
|
||||
* @OA\\Property(property="value", type="object")
|
||||
* )
|
||||
* @OA\\Schema(
|
||||
* schema="mixedList",
|
||||
* @OA\\Property(property="fields", type="array", @OA\\Items(oneOf={
|
||||
* @OA\\Schema(ref="#/components/schemas/StringList"),
|
||||
* @OA\\Schema(ref="#/components/schemas/String"),
|
||||
* @OA\\Schema(ref="#/components/schemas/Object")
|
||||
* }))
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p>This will resolve into this YAML</p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">StringList</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">value</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> array
|
||||
<span class="token key atrule">items</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">anyOf</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
<span class="token key atrule">String</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">value</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
<span class="token key atrule">Object</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">value</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
<span class="token key atrule">mixedList</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">fields</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> array
|
||||
<span class="token key atrule">items</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">oneOf</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/StringList'</span>
|
||||
<span class="token punctuation">-</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/String'</span>
|
||||
<span class="token punctuation">-</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/Object'</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
</code></pre></div><h2 id="referencing-a-security-scheme" tabindex="-1">Referencing a security scheme <a class="header-anchor" href="#referencing-a-security-scheme" aria-hidden="true">#</a></h2><p>An API might have zero or more security schemes. These are defined at the top level and vary from simple to complex:</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\SecurityScheme(
|
||||
* type="apiKey",
|
||||
* name="api_key",
|
||||
* in="header",
|
||||
* securityScheme="api_key"
|
||||
* )
|
||||
*
|
||||
* @OA\\SecurityScheme(
|
||||
* type="oauth2",
|
||||
* securityScheme="petstore_auth",
|
||||
* @OA\\Flow(
|
||||
* authorizationUrl="http://petstore.swagger.io/oauth/dialog",
|
||||
* flow="implicit",
|
||||
* scopes={
|
||||
* "read:pets": "read your pets",
|
||||
* "write:pets": "modify pets in your account"
|
||||
* }
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p>To declare an endpoint as secure and define what security schemes are available to authenticate a client it needs to be added to the operation, for example:</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Get(
|
||||
* path="/api/secure/",
|
||||
* summary="Requires authentication"
|
||||
* ),
|
||||
* security={ {"api_key": {}} }
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><div class="tip custom-block"><p class="custom-block-title">Endpoints can support multiple security schemes and have custom options too:</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Get(
|
||||
* path="/api/secure/",
|
||||
* summary="Requires authentication"
|
||||
* ),
|
||||
* security={
|
||||
* { "api_key": {} },
|
||||
* { "petstore_auth": {"write:pets", "read:pets"} }
|
||||
* }
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div></div><h2 id="file-upload-with-headers" tabindex="-1">File upload with headers <a class="header-anchor" href="#file-upload-with-headers" aria-hidden="true">#</a></h2><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Post(
|
||||
* path="/v1/media/upload",
|
||||
* summary="Upload document",
|
||||
* description="",
|
||||
* tags={"Media"},
|
||||
* @OA\\RequestBody(
|
||||
* required=true,
|
||||
* @OA\\MediaType(
|
||||
* mediaType="application/octet-stream",
|
||||
* @OA\\Schema(
|
||||
* required={"content"},
|
||||
* @OA\\Property(
|
||||
* description="Binary content of file",
|
||||
* property="content",
|
||||
* type="string",
|
||||
* format="binary"
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\\Response(
|
||||
* response=200, description="Success",
|
||||
* @OA\\Schema(type="string")
|
||||
* ),
|
||||
* @OA\\Response(
|
||||
* response=400, description="Bad Request"
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="set-the-xml-root-name" tabindex="-1">Set the XML root name <a class="header-anchor" href="#set-the-xml-root-name" aria-hidden="true">#</a></h2><p>The <code>OA\\Xml</code> annotation may be used to set the XML root element for a given <code>@OA\\XmlContent</code> response body</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Schema(
|
||||
* schema="Error",
|
||||
* @OA\\Property(property="message"),
|
||||
* @OA\\Xml(name="details")
|
||||
* )
|
||||
*/</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @OA\\Post(
|
||||
* path="/foobar",
|
||||
* @OA\\Response(
|
||||
* response=400,
|
||||
* description="Request error",
|
||||
* @OA\\XmlContent(ref="#/components/schemas/Error",
|
||||
* @OA\\Xml(name="error")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="upload-multipart-form-data" tabindex="-1">upload multipart/form-data <a class="header-anchor" href="#upload-multipart-form-data" aria-hidden="true">#</a></h2><p>Form posts are <code>@OA\\Post</code> requests with a <code>multipart/form-data</code> <code>@OA\\RequestBody</code>. The relevant bit looks something like this</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Post(
|
||||
* path="/v1/user/update",
|
||||
* summary="Form post",
|
||||
* @OA\\RequestBody(
|
||||
* @OA\\MediaType(
|
||||
* mediaType="multipart/form-data",
|
||||
* @OA\\Schema(
|
||||
* @OA\\Property(property="name"),
|
||||
* @OA\\Property(
|
||||
* description="file to upload",
|
||||
* property="avatar",
|
||||
* type="string",
|
||||
* format="binary",
|
||||
* ),
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\\Response(response=200, description="Success")
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="default-security-scheme-for-all-endpoints" tabindex="-1">Default security scheme for all endpoints <a class="header-anchor" href="#default-security-scheme-for-all-endpoints" aria-hidden="true">#</a></h2><p>Unless specified each endpoint needs to declare what security schemes it supports. However, there is a way to also configure security schemes globally for the whole API.</p><p>This is done on the <code>@OA\\OpenApi</code> annotations:</p>`,32),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Annotations")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\OpenApi(
|
||||
* security={{"bearerAuth": {}}}
|
||||
* )
|
||||
*
|
||||
* @OA\\SecurityScheme(
|
||||
* securityScheme="bearerAuth",
|
||||
* type="http",
|
||||
* scheme="bearer"
|
||||
* )
|
||||
*/`),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Attributes")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OAT"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("OpenApi")]),n("span",{class:"token punctuation"},"("),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"security"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),n("span",{class:"token punctuation"},"["),n("span",{class:"token string single-quoted-string"},"'bearerAuth'"),s(),n("span",{class:"token operator"},"=>"),s(),n("span",{class:"token punctuation"},"["),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),s(`
|
||||
`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("Components")]),n("span",{class:"token punctuation"},"("),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"securitySchemes"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"new"),s(),n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("SecurityScheme")]),n("span",{class:"token punctuation"},"("),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"securityScheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearerAuth'"),n("span",{class:"token punctuation"},","),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"type"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'http'"),n("span",{class:"token punctuation"},","),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"scheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearer'"),s(`
|
||||
`),n("span",{class:"token punctuation"},")"),s(`
|
||||
`),n("span",{class:"token punctuation"},"]"),s(`
|
||||
`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),m=e(`<h2 id="nested-objects" tabindex="-1">Nested objects <a class="header-anchor" href="#nested-objects" aria-hidden="true">#</a></h2><p>Complex, nested data structures are defined by nesting <code>@OA\\Property</code> annotations inside others (with <code>type="object"</code>).</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Schema(
|
||||
* schema="Profile",
|
||||
* type="object",
|
||||
*
|
||||
* @OA\\Property(
|
||||
* property="Status",
|
||||
* type="string",
|
||||
* example="0"
|
||||
* ),
|
||||
*
|
||||
* @OA\\Property(
|
||||
* property="Group",
|
||||
* type="object",
|
||||
*
|
||||
* @OA\\Property(
|
||||
* property="ID",
|
||||
* description="ID de grupo",
|
||||
* type="number",
|
||||
* example=-1
|
||||
* ),
|
||||
*
|
||||
* @OA\\Property(
|
||||
* property="Name",
|
||||
* description="Nombre de grupo",
|
||||
* type="string",
|
||||
* example="Superadmin"
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
|
||||
</code></pre></div><h2 id="documenting-union-type-response-data-using-oneof" tabindex="-1">Documenting union type response data using <code>oneOf</code> <a class="header-anchor" href="#documenting-union-type-response-data-using-oneof" aria-hidden="true">#</a></h2><p>A response with either a single or a list of <code>QualificationHolder</code>'s.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Response(
|
||||
* response=200,
|
||||
* @OA\\JsonContent(
|
||||
* oneOf={
|
||||
* @OA\\Schema(ref="#/components/schemas/QualificationHolder"),
|
||||
* @OA\\Schema(
|
||||
* type="array",
|
||||
* @OA\\Items(ref="#/components/schemas/QualificationHolder")
|
||||
* )
|
||||
* }
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="reusing-responses" tabindex="-1">Reusing responses <a class="header-anchor" href="#reusing-responses" aria-hidden="true">#</a></h2><p>Global responses are found under <code>/components/responses</code> and can be referenced/shared just like schema definitions (models)</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Response(
|
||||
* response="product",
|
||||
* description="All information about a product",
|
||||
* @OA\\JsonContent(ref="#/components/schemas/Product")
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">ProductResponse</span> <span class="token punctuation">{</span><span class="token punctuation">}</span>
|
||||
|
||||
<span class="token comment">// ...</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">ProductController</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token comment">/**
|
||||
* @OA\\Get(
|
||||
* tags={"Products"},
|
||||
* path="/products/{product_id}",
|
||||
* @OA\\Response(
|
||||
* response="default",
|
||||
* ref="#/components/responses/product"
|
||||
* )
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">getProduct</span><span class="token punctuation">(</span><span class="token variable">$id</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><div class="tip custom-block"><p class="custom-block-title">\`response\` parameter is always required</p><p>Even if referencing a shared response definition, the <code>response</code> parameter is still required.</p></div><h2 id="mediatype" tabindex="-1">mediaType="<em>/</em>" <a class="header-anchor" href="#mediatype" aria-hidden="true">#</a></h2><p>Using <code>*/*</code> as <code>mediaType</code> is not possible using annotations.</p><p><strong>Example:</strong></p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\MediaType(
|
||||
* mediaType="*/</span><span class="token operator">*</span><span class="token string double-quoted-string">",
|
||||
* @OA\\Schema(type="</span><span class="token keyword type-declaration">string</span><span class="token string double-quoted-string">",format="</span>binary"<span class="token punctuation">)</span>
|
||||
<span class="token operator">*</span> <span class="token punctuation">)</span>
|
||||
<span class="token operator">*</span><span class="token operator">/</span>
|
||||
</code></pre></div><p>The doctrine annotations library used for parsing annotations does not handle this and will interpret the <code>*/</code> bit as the end of the comment.</p><p>Using just <code>*</code> or <code>application/octet-stream</code> might be usable workarounds.</p><h2 id="warning-about-multiple-response-with-same-response-200" tabindex="-1">Warning about <code>Multiple response with same response="200"</code> <a class="header-anchor" href="#warning-about-multiple-response-with-same-response-200" aria-hidden="true">#</a></h2><p>There are two scenarios where this can happen</p><ol><li>A single endpoint contains two responses with the same <code>response</code> value.</li><li>There are multiple global response declared, again more than one with the same <code>response</code> value.</li></ol><h2 id="callbacks" tabindex="-1">Callbacks <a class="header-anchor" href="#callbacks" aria-hidden="true">#</a></h2><p>The API does include basic support for callbacks. However, this needs to be set up mostly manually.</p><p><strong>Example</strong></p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* ...
|
||||
*
|
||||
* callbacks={
|
||||
* "onChange"={
|
||||
* "{$request.query.callbackUrl}"={
|
||||
* "post": {
|
||||
* "requestBody": @OA\\RequestBody(
|
||||
* description="subscription payload",
|
||||
* @OA\\MediaType(mediaType="application/json", @OA\\Schema(
|
||||
* @OA\\Property(property="timestamp", type="string", format="date-time", description="time of change")
|
||||
* ))
|
||||
* )
|
||||
* },
|
||||
* "responses": {
|
||||
* "202": {
|
||||
* "description": "Your server implementation should return this HTTP status code if the data was received successfully"
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* ...
|
||||
*
|
||||
*/</span>
|
||||
</code></pre></div><h2 id="mostly-virtual-models" tabindex="-1">(Mostly) virtual models <a class="header-anchor" href="#mostly-virtual-models" aria-hidden="true">#</a></h2><p>Typically, a model is annotated by adding a <code>@OA\\Schema</code> annotation to the class and then individual <code>@OA\\Property</code> annotations to the individually declared class properties.</p><p>It is possible, however, to nest <code>O@\\Property</code> annotations inside a schema even without properties. In fact, all that is needed is a code anchor - e.g. an empty class.</p><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OA</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span>
|
||||
<span class="token attribute-class-name class-name">properties</span><span class="token punctuation">:</span> <span class="token punctuation">[</span>
|
||||
<span class="token string single-quoted-string">'name'</span> <span class="token operator">=></span> <span class="token attribute-class-name class-name">new</span> <span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">property</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'name'</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">type</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'string'</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
|
||||
<span class="token string single-quoted-string">'email'</span> <span class="token operator">=></span> <span class="token attribute-class-name class-name">new</span> <span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">property</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'email'</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">type</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'string'</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
|
||||
<span class="token punctuation">]</span>
|
||||
<span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">User</span> <span class="token punctuation">{</span><span class="token punctuation">}</span>
|
||||
</code></pre></div><h2 id="using-class-name-as-type-instead-of-references" tabindex="-1">Using class name as type instead of references <a class="header-anchor" href="#using-class-name-as-type-instead-of-references" aria-hidden="true">#</a></h2><p>Typically, when referencing schemas this is done using <code>$ref</code>'s</p><div class="language-php"><pre><code><span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">schema</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'user'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">User</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Book</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token comment">/**
|
||||
* @var User
|
||||
*/</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">ref</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'#/components/schemas/user'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token variable">$author</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p>This works, but is not very convenient.</p><p>First, when using custom schema names (<code>schema: 'user'</code>), this needs to be taken into account everywhere. Secondly, having to write <code>ref: '#/components/schemas/user'</code> is tedious and error-prone.</p><p>Using attributes all this changes as we can take advantage of PHP itself by referring to a schema by its (fully qualified) class name.</p><p>With the same <code>User</code> schema as before, the <code>Book::author</code> property could be written in a few different ways</p><div class="language-php"><pre><code> <span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> User author<span class="token punctuation">;</span>
|
||||
</code></pre></div><p><strong>or</strong></p><div class="language-php"><pre><code> <span class="token comment">/**
|
||||
* @var User
|
||||
*/</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> author<span class="token punctuation">;</span>
|
||||
</code></pre></div><p><strong>or</strong></p><div class="language-php"><pre><code> <span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">type</span><span class="token punctuation">:</span> <span class="token attribute-class-name class-name">User</span><span class="token operator">::</span><span class="token constant">class</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> author<span class="token punctuation">;</span>
|
||||
</code></pre></div><h2 id="enums" tabindex="-1">Enums <a class="header-anchor" href="#enums" aria-hidden="true">#</a></h2><p>As of PHP 8.1 there is native support for <code>enum</code>'s.</p><p><code>swagger-php</code> supports enums in much the same way as class names can be used to reference schemas.</p><p><strong>Example</strong></p><div class="language-php"><pre><code><span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name">Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">enum</span> <span class="token class-name-definition class-name">State</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">OPEN</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">MERGED</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">case</span> <span class="token constant">DECLINED</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name">Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">PullRequest</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OAT<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token class-name type-declaration">State</span> <span class="token variable">$state</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p>However, in this case the schema generated for <code>State</code> will be an enum:</p><div class="language-yaml"><pre><code><span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">PullRequest</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">state</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">$ref</span><span class="token punctuation">:</span> <span class="token string">'#/components/schemas/State'</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> object
|
||||
<span class="token key atrule">State</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">enum</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> OPEN
|
||||
<span class="token punctuation">-</span> MERGED
|
||||
<span class="token punctuation">-</span> DECLINED
|
||||
</code></pre></div><h2 id="multi-value-query-parameter-q-1-q-1" tabindex="-1">Multi value query parameter: <code>&q[]=1&q[]=1</code> <a class="header-anchor" href="#multi-value-query-parameter-q-1-q-1" aria-hidden="true">#</a></h2><p>PHP allows to have query parameters multiple times in the url and will combine the values to an array if the parameter name uses trailing <code>[]</code>. In fact, it is possible to create nested arrays too by using more than one pair of <code>[]</code>.</p><p>In terms of OpenAPI, the parameters can be considered a single parameter with a list of values.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Get(
|
||||
* path="/api/endpoint",
|
||||
* description="The endpoint",
|
||||
* operationId="endpoint",
|
||||
* tags={"endpoints"},
|
||||
* @OA\\Parameter(
|
||||
* name="things[]",
|
||||
* in="query",
|
||||
* description="A list of things.",
|
||||
* required=false,
|
||||
* @OA\\Schema(
|
||||
* type="array",
|
||||
* @OA\\Items(type="integer")
|
||||
* )
|
||||
* ),
|
||||
* @OA\\Response(response="200", description="All good")
|
||||
* )
|
||||
*/</span>
|
||||
</code></pre></div><p>The corresponding bit of the spec will look like this:</p><div class="language-yaml"><pre><code> <span class="token key atrule">parameters</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span>
|
||||
<span class="token key atrule">name</span><span class="token punctuation">:</span> <span class="token string">'things[]'</span>
|
||||
<span class="token key atrule">in</span><span class="token punctuation">:</span> query
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">'A list of things.'</span>
|
||||
<span class="token key atrule">required</span><span class="token punctuation">:</span> <span class="token boolean important">false</span>
|
||||
<span class="token key atrule">schema</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> array
|
||||
<span class="token key atrule">items</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> integer
|
||||
</code></pre></div><p><code>swagger-ui</code> will show a form that allows to add/remove items (<code>integer</code> values in this case) to/from a list and post those values as something like <code>?things[]=1&things[]=2&things[]=0</code></p><h2 id="custom-response-classes" tabindex="-1">Custom response classes <a class="header-anchor" href="#custom-response-classes" aria-hidden="true">#</a></h2><p>Even with using refs there is a bit of overhead in sharing responses. One way around that is to write your own response classes. The beauty is that in your custom <code>__construct()</code> method you can prefill as much as you need.</p><p>Best of all, this works for both annotations and attributes.</p><p>Example:</p><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OA</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @Annotation
|
||||
*/</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content">\\<span class="token attribute-class-name class-name">Attribute</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name class-name-fully-qualified"><span class="token punctuation">\\</span>Attribute</span><span class="token operator">::</span><span class="token constant">TARGET_CLASS</span> <span class="token operator">|</span> <span class="token attribute-class-name class-name class-name-fully-qualified"><span class="token punctuation">\\</span>Attribute</span><span class="token operator">::</span><span class="token constant">TARGET_METHOD</span> <span class="token operator">|</span> <span class="token attribute-class-name class-name class-name-fully-qualified"><span class="token punctuation">\\</span>Attribute</span><span class="token operator">::</span><span class="token constant">IS_REPEATABLE</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">BadRequest</span> <span class="token keyword">extends</span> <span class="token class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Response</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">__construct</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token keyword static-context">parent</span><span class="token operator">::</span><span class="token function">__construct</span><span class="token punctuation">(</span><span class="token argument-name">response</span><span class="token punctuation">:</span> <span class="token number">400</span><span class="token punctuation">,</span> <span class="token argument-name">description</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'Bad request'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Controller</span>
|
||||
<span class="token punctuation">{</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Get</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">path</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'/foo'</span><span class="token punctuation">,</span> <span class="token attribute-class-name class-name">responses</span><span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token attribute-class-name class-name">new</span> <span class="token attribute-class-name class-name">BadRequest</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">get</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Post</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">path</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'/foo'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name">BadRequest</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">post</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @OA\\Delete(
|
||||
* path="/foo",
|
||||
* @BadRequest()
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">delete</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><div class="tip custom-block"><p class="custom-block-title">Annotations only?</p><p>If you are only interested in annotations you canleave out the attribute setup line (<code>#[\\Attribute...</code>) for <code>BadRequest</code>.</p><p>Furthermore, your custom annotations should extend from the <code>OpenApi\\Annotations</code> namespace.</p></div><h2 id="annotating-class-constants" tabindex="-1">Annotating class constants <a class="header-anchor" href="#annotating-class-constants" aria-hidden="true">#</a></h2><div class="language-php"><pre><code><span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OA</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Schema</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">Airport</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Property</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">property</span><span class="token operator">=</span><span class="token string single-quoted-string">'kind'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">const</span> <span class="token constant">KIND</span> <span class="token operator">=</span> <span class="token string single-quoted-string">'Airport'</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p>The <code>const</code> property is supported in OpenApi 3.1.0.</p><div class="language-yaml"><pre><code><span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Airport</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">kind</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">const</span><span class="token punctuation">:</span> Airport
|
||||
</code></pre></div><p>For 3.0.0 this is serialized into a single value <code>enum</code>.</p><div class="language-yaml"><pre><code><span class="token key atrule">components</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">schemas</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">Airport</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">properties</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">kind</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> string
|
||||
<span class="token key atrule">enum</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span> Airport
|
||||
</code></pre></div>`,65);function h(y,q,g,f,b,A){const t=u("codeblock");return l(),p("div",null,[r,c(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),m])}var w=o(i,[["render",h]]);export{O as __pageData,w as default};
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
import{_ as o,c as p,b as c,w as a,a as e,r as u,o as l,d as n,e as s}from"./app.3ef9e972.js";const O='{"title":"Cookbook","description":"","frontmatter":{},"headers":[{"level":2,"title":"x-tagGroups","slug":"x-taggroups"},{"level":2,"title":"Adding examples to @OA\\\\Response","slug":"adding-examples-to-oa-response"},{"level":2,"title":"External documentation","slug":"external-documentation"},{"level":2,"title":"Properties with union types","slug":"properties-with-union-types"},{"level":2,"title":"Referencing a security scheme","slug":"referencing-a-security-scheme"},{"level":2,"title":"File upload with headers","slug":"file-upload-with-headers"},{"level":2,"title":"Set the XML root name","slug":"set-the-xml-root-name"},{"level":2,"title":"upload multipart/form-data","slug":"upload-multipart-form-data"},{"level":2,"title":"Default security scheme for all endpoints","slug":"default-security-scheme-for-all-endpoints"},{"level":2,"title":"Nested objects","slug":"nested-objects"},{"level":2,"title":"Documenting union type response data using oneOf","slug":"documenting-union-type-response-data-using-oneof"},{"level":2,"title":"Reusing responses","slug":"reusing-responses"},{"level":2,"title":"mediaType=\\"/\\"","slug":"mediatype"},{"level":2,"title":"Warning about Multiple response with same response=\\"200\\"","slug":"warning-about-multiple-response-with-same-response-200"},{"level":2,"title":"Callbacks","slug":"callbacks"},{"level":2,"title":"(Mostly) virtual models","slug":"mostly-virtual-models"},{"level":2,"title":"Using class name as type instead of references","slug":"using-class-name-as-type-instead-of-references"},{"level":2,"title":"Enums","slug":"enums"},{"level":2,"title":"Multi value query parameter: &q[]=1&q[]=1","slug":"multi-value-query-parameter-q-1-q-1"},{"level":2,"title":"Custom response classes","slug":"custom-response-classes"},{"level":2,"title":"Annotating class constants","slug":"annotating-class-constants"}],"relativePath":"guide/cookbook.md"}',i={},r=e("",32),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Annotations")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\OpenApi(
|
||||
* security={{"bearerAuth": {}}}
|
||||
* )
|
||||
*
|
||||
* @OA\\SecurityScheme(
|
||||
* securityScheme="bearerAuth",
|
||||
* type="http",
|
||||
* scheme="bearer"
|
||||
* )
|
||||
*/`),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Attributes")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OAT"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("OpenApi")]),n("span",{class:"token punctuation"},"("),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"security"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),n("span",{class:"token punctuation"},"["),n("span",{class:"token string single-quoted-string"},"'bearerAuth'"),s(),n("span",{class:"token operator"},"=>"),s(),n("span",{class:"token punctuation"},"["),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),n("span",{class:"token punctuation"},"]"),s(`
|
||||
`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("Components")]),n("span",{class:"token punctuation"},"("),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"securitySchemes"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"new"),s(),n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OAT"),n("span",{class:"token punctuation"},"\\"),s("SecurityScheme")]),n("span",{class:"token punctuation"},"("),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"securityScheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearerAuth'"),n("span",{class:"token punctuation"},","),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"type"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'http'"),n("span",{class:"token punctuation"},","),s(`
|
||||
`),n("span",{class:"token attribute-class-name class-name"},"scheme"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'bearer'"),s(`
|
||||
`),n("span",{class:"token punctuation"},")"),s(`
|
||||
`),n("span",{class:"token punctuation"},"]"),s(`
|
||||
`),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),m=e("",65);function h(y,q,g,f,b,A){const t=u("codeblock");return l(),p("div",null,[r,c(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),m])}var w=o(i,[["render",h]]);export{O as __pageData,w as default};
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
import{_ as n,c as e,o as a,a as s}from"./app.3ef9e972.js";const k='{"title":"FAQ","description":"","frontmatter":{},"headers":[{"level":2,"title":"Warning: Required @OA\\\\Info() not found","slug":"warning-required-oa-info-not-found"},{"level":2,"title":"Annotations missing","slug":"annotations-missing"},{"level":2,"title":"Skipping unknown \\\\SomeClass","slug":"skipping-unknown-someclass"},{"level":3,"title":"Using the -b --bootstrap option","slug":"using-the-b-bootstrap-option"},{"level":3,"title":"Namespace mismatch","slug":"namespace-mismatch"},{"level":2,"title":"No output from openapi command line tool","slug":"no-output-from-openapi-command-line-tool"}],"relativePath":"guide/faq.md"}',t={},o=s(`<h1 id="faq" tabindex="-1">FAQ <a class="header-anchor" href="#faq" aria-hidden="true">#</a></h1><h2 id="warning-required-oa-info-not-found" tabindex="-1">Warning: Required <code>@OA\\Info()</code> not found <a class="header-anchor" href="#warning-required-oa-info-not-found" aria-hidden="true">#</a></h2><p>With adding support for <a href="https://www.php.net/manual/en/language.attributes.php" target="_blank" rel="noopener noreferrer">PHP attributes</a> in version 4, some architectural changes had to be made.</p><p>One of those changes is that placing annotations in your source files is now subject to the same limitations as attributes. These limits are dictated by the PHP reflection API, specifically where it provides access to attributes and doc comments.</p><p>This means stand-alone annotations are no longer supported and ignored as <code>swagger-php</code> cannot <em>"see"</em> them any more.</p><p>Supported locations:</p><ul><li>class</li><li>interface</li><li>trait</li><li>method</li><li>property</li><li>class/interface const</li></ul><p>Most commonly this manifests with a warning about the required <code>@OA\\Info</code> not being found. While most annotations have specific related code, the info annotation (and a few more) is kind of global.</p><p>The simplest solution to avoid this issue is to add a 'dummy' class to the docblock and add all 'global' annotations (e.g. <code>Tag</code>, <code>Server</code>, <code>SecurityScheme</code>, etc.) <strong>in a single docblock</strong> to that class.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* @OA\\Tag(
|
||||
* name="user",
|
||||
* description="User related operations"
|
||||
* )
|
||||
* @OA\\Info(
|
||||
* version="1.0",
|
||||
* title="Example API",
|
||||
* description="Example info",
|
||||
* @OA\\Contact(name="Swagger API Team")
|
||||
* )
|
||||
* @OA\\Server(
|
||||
* url="https://example.localhost",
|
||||
* description="API server"
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">OpenApiSpec</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p><strong>As of version 4.8 the <code>doctrine/annotations</code> library is optional and might cause the same message.</strong></p><p>If this is the case, <code>doctrine annotations</code> must be installed separately:</p><div class="language-shell"><pre><code><span class="token function">composer</span> require doctrine/annotations
|
||||
</code></pre></div><h2 id="annotations-missing" tabindex="-1">Annotations missing <a class="header-anchor" href="#annotations-missing" aria-hidden="true">#</a></h2><p>Another side effect of using reflection is that <code>swagger-php</code> <em>"can't see"</em> multiple consecutive docblocks any more as the PHP reflection API only provides access to the docblock closest to a given structural element.</p><div class="language-php"><pre><code><span class="token keyword">class</span> <span class="token class-name-definition class-name">Controller</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token comment">/**
|
||||
* @OA\\Delete(
|
||||
* path="/api/v0.0.2/notifications/{id}",
|
||||
* operationId="deleteNotificationById",
|
||||
* summary="Delete notification by ID",
|
||||
* @OA\\Parameter(name="id", in="path", @OA\\Schema(type="integer")),
|
||||
* @OA\\Response(response=200, description="OK"),
|
||||
* @OA\\Response(response=400, description="Bad Request")
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token comment">/**
|
||||
* Delete notification by ID.
|
||||
*
|
||||
* @param Request $request
|
||||
* @param AppNotification $notification
|
||||
*
|
||||
* @return Response
|
||||
* @throws Exception
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">destroy</span><span class="token punctuation">(</span><span class="token class-name type-declaration">Request</span> <span class="token variable">$request</span><span class="token punctuation">,</span> <span class="token class-name type-declaration">AppNotification</span> <span class="token variable">$notification</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">//</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p>In this case the simplest solution is to merge both docblocks. As an additional benefit the duplication of the summary can be avoided.</p><p>In this improved version <code>swagger-php</code> will automatically use the docblock summary just as explicitly done above.</p><div class="language-php"><pre><code><span class="token keyword">class</span> <span class="token class-name-definition class-name">Controller</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token comment">/**
|
||||
* Delete notification by ID.
|
||||
*
|
||||
* @OA\\Delete(
|
||||
* path="/api/v0.0.2/notifications/{id}",
|
||||
* operationId="deleteNotificationById",
|
||||
* @OA\\Parameter(name="id", in="path", @OA\\Schema(type="integer")),
|
||||
* @OA\\Response(response=200, description="OK"),
|
||||
* @OA\\Response(response=400, description="Bad Request")
|
||||
* )
|
||||
*
|
||||
* @param Request $request
|
||||
* @param AppNotification $notification
|
||||
*
|
||||
* @return Response
|
||||
* @throws Exception
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">destroy</span><span class="token punctuation">(</span><span class="token class-name type-declaration">Request</span> <span class="token variable">$request</span><span class="token punctuation">,</span> <span class="token class-name type-declaration">AppNotification</span> <span class="token variable">$notification</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token comment">//</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p><strong>Resulting spec:</strong></p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">paths</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">'/api/v0.0.2/notifications/{id}'</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">delete</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">summary</span><span class="token punctuation">:</span> <span class="token string">'XDelete notification by ID.'</span>
|
||||
<span class="token key atrule">operationId</span><span class="token punctuation">:</span> deleteNotificationById
|
||||
<span class="token key atrule">parameters</span><span class="token punctuation">:</span>
|
||||
<span class="token punctuation">-</span>
|
||||
<span class="token key atrule">name</span><span class="token punctuation">:</span> id
|
||||
<span class="token key atrule">in</span><span class="token punctuation">:</span> path
|
||||
<span class="token key atrule">schema</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">type</span><span class="token punctuation">:</span> integer
|
||||
<span class="token key atrule">responses</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">'200'</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> OK
|
||||
<span class="token key atrule">'400'</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">'Bad Request'</span>
|
||||
|
||||
</code></pre></div><h2 id="skipping-unknown-someclass" tabindex="-1">Skipping unknown <code>\\SomeClass</code> <a class="header-anchor" href="#skipping-unknown-someclass" aria-hidden="true">#</a></h2><p>This message means that <code>swagger-php</code> has tried to use reflection to inspect <code>\\SomeClass</code> and that PHP could not find/load that class. Effectively, this means that <code>class_exists("\\SomeClass")</code> returns <code>false</code>.</p><h3 id="using-the-b-bootstrap-option" tabindex="-1">Using the <code>-b</code> <code>--bootstrap</code> option <a class="header-anchor" href="#using-the-b-bootstrap-option" aria-hidden="true">#</a></h3><p>There are a number of reasons why this could happen. If you are using the <code>openapi</code> command line tool from a global installation typically the application classloader (composer) is not active. With you application root being <code>myapp</code> you could try:</p><div class="language-shell"><pre><code>openapi <span class="token parameter variable">-b</span> myapp/vendor/autoload.php myapp/src
|
||||
</code></pre></div><p>The <code>-b</code> allows to execute some extra PHP code to load whatever is needed to register your apps classloader with PHP.</p><h3 id="namespace-mismatch" tabindex="-1">Namespace mismatch <a class="header-anchor" href="#namespace-mismatch" aria-hidden="true">#</a></h3><p>Another reason for this error could be that your class actually has the wrong namespace (or no namespace at all!).</p><p>Depending on your framework this might still work in the context of your app, but the composer autoloader alone might not be able to load your class (assuming you are using composer).</p><h2 id="no-output-from-openapi-command-line-tool" tabindex="-1">No output from <code>openapi</code> command line tool <a class="header-anchor" href="#no-output-from-openapi-command-line-tool" aria-hidden="true">#</a></h2><p>Depending on your PHP configuration, running the <code>openapi</code> command line tool might result in no output at all.</p><p>The reason for this is that <code>openapi</code> currently uses the <a href="https://www.php.net/manual/en/function.error-log.php" target="_blank" rel="noopener noreferrer"><code>error_log</code></a> function for all output.</p><p>So if this is configured to write to a file, then it will seem like the command is broken.</p>`,34),i=[o];function p(c,l,r,u,d,h){return a(),e("div",null,i)}var f=n(t,[["render",p]]);export{k as __pageData,f as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as n,c as e,o as a,a as s}from"./app.3ef9e972.js";const k='{"title":"FAQ","description":"","frontmatter":{},"headers":[{"level":2,"title":"Warning: Required @OA\\\\Info() not found","slug":"warning-required-oa-info-not-found"},{"level":2,"title":"Annotations missing","slug":"annotations-missing"},{"level":2,"title":"Skipping unknown \\\\SomeClass","slug":"skipping-unknown-someclass"},{"level":3,"title":"Using the -b --bootstrap option","slug":"using-the-b-bootstrap-option"},{"level":3,"title":"Namespace mismatch","slug":"namespace-mismatch"},{"level":2,"title":"No output from openapi command line tool","slug":"no-output-from-openapi-command-line-tool"}],"relativePath":"guide/faq.md"}',t={},o=s("",34),i=[o];function p(c,l,r,u,d,h){return a(),e("div",null,i)}var f=n(t,[["render",p]]);export{k as __pageData,f as default};
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
import{_ as a,c as n,o as s,a as e}from"./app.3ef9e972.js";const m='{"title":"Generating OpenAPI documents","description":"","frontmatter":{},"headers":[{"level":2,"title":"./bin/openapi","slug":"bin-openapi"},{"level":2,"title":"Using PHP","slug":"using-php"}],"relativePath":"guide/generating-openapi-documents.md"}',t={},p=e(`<h1 id="generating-openapi-documents" tabindex="-1">Generating OpenAPI documents <a class="header-anchor" href="#generating-openapi-documents" aria-hidden="true">#</a></h1><h2 id="bin-openapi" tabindex="-1"><code>./bin/openapi</code> <a class="header-anchor" href="#bin-openapi" aria-hidden="true">#</a></h2><p><code>swagger-php</code> includes a command line tool <code>./bin/openapi</code>. This can be used to generate OpenAPI documents.</p><div class="language-shell"><pre><code><span class="token operator">></span> ./vendor/bin/openapi app <span class="token parameter variable">-o</span> openapi.yaml
|
||||
</code></pre></div><div class="tip custom-block"><p class="custom-block-title">Output Format</p><p>By default the output format is YAML. If a filename is given (via <code>--output</code> or <code>-o</code>) the tool will use the file extension to determine the format.</p><p>The <code>--format</code> option can be used to force a specific format.</p></div><p>For a list of all available options use the <code>-h</code> option</p><div class="language-shell"><pre><code><span class="token operator">></span> ./bin/openapi <span class="token parameter variable">-h</span>
|
||||
|
||||
Usage: openapi <span class="token punctuation">[</span>--option value<span class="token punctuation">]</span> <span class="token punctuation">[</span>/path/to/project <span class="token punctuation">..</span>.<span class="token punctuation">]</span>
|
||||
|
||||
Options:
|
||||
<span class="token parameter variable">--config</span> <span class="token punctuation">(</span>-c<span class="token punctuation">)</span> Generator config
|
||||
ex: <span class="token parameter variable">-c</span> <span class="token assign-left variable">operationId.hash</span><span class="token operator">=</span>false
|
||||
<span class="token parameter variable">--legacy</span> <span class="token punctuation">(</span>-l<span class="token punctuation">)</span> Use legacy TokenAnalyser<span class="token punctuation">;</span> default is the new ReflectionAnalyser
|
||||
<span class="token parameter variable">--output</span> <span class="token punctuation">(</span>-o<span class="token punctuation">)</span> Path to store the generated documentation.
|
||||
ex: <span class="token parameter variable">--output</span> openapi.yaml
|
||||
<span class="token parameter variable">--exclude</span> <span class="token punctuation">(</span>-e<span class="token punctuation">)</span> Exclude path<span class="token punctuation">(</span>s<span class="token punctuation">)</span>.
|
||||
ex: <span class="token parameter variable">--exclude</span> vendor,library/Zend
|
||||
<span class="token parameter variable">--pattern</span> <span class="token punctuation">(</span>-n<span class="token punctuation">)</span> Pattern of files to scan.
|
||||
ex: <span class="token parameter variable">--pattern</span> <span class="token string">"*.php"</span> or <span class="token parameter variable">--pattern</span> <span class="token string">"/\\.(phps|php)$/"</span>
|
||||
<span class="token parameter variable">--bootstrap</span> <span class="token punctuation">(</span>-b<span class="token punctuation">)</span> Bootstrap a php <span class="token function">file</span> <span class="token keyword">for</span> defining constants, etc.
|
||||
ex: <span class="token parameter variable">--bootstrap</span> config/constants.php
|
||||
<span class="token parameter variable">--processor</span> <span class="token punctuation">(</span>-p<span class="token punctuation">)</span> Register an additional processor.
|
||||
<span class="token parameter variable">--format</span> <span class="token punctuation">(</span>-f<span class="token punctuation">)</span> Force yaml or json.
|
||||
<span class="token parameter variable">--debug</span> <span class="token punctuation">(</span>-d<span class="token punctuation">)</span> Show additional error information.
|
||||
<span class="token parameter variable">--version</span> The OpenAPI version<span class="token punctuation">;</span> defaults to <span class="token number">3.0</span>.0.
|
||||
<span class="token parameter variable">--help</span> <span class="token punctuation">(</span>-h<span class="token punctuation">)</span> Display this <span class="token builtin class-name">help</span> message.
|
||||
</code></pre></div><h2 id="using-php" tabindex="-1">Using PHP <a class="header-anchor" href="#using-php" aria-hidden="true">#</a></h2><p>Depending on your use case PHP code can also be used to generate OpenAPI documents in a more dynamic way.</p><p>In its simplest form this may look something like</p><div class="language-php"><pre><code><span class="token php language-php"><span class="token delimiter important"><?php</span>
|
||||
<span class="token keyword">require</span><span class="token punctuation">(</span><span class="token string double-quoted-string">"vendor/autoload.php"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token class-name class-name-fully-qualified static-context"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Generator</span><span class="token operator">::</span><span class="token function">scan</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string single-quoted-string">'/path/to/project'</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token function">header</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'Content-Type: application/x-yaml'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">echo</span> <span class="token variable">$openapi</span><span class="token operator">-></span><span class="token function">toYaml</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">Programming API</p><p>Details about the <code>swagger-php</code> API can be found in the <a href="./../reference/">reference</a>.</p></div>`,12),o=[p];function c(i,l,r,u,d,k){return s(),n("div",null,o)}var g=a(t,[["render",c]]);export{m as __pageData,g as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as a,c as n,o as s,a as e}from"./app.3ef9e972.js";const m='{"title":"Generating OpenAPI documents","description":"","frontmatter":{},"headers":[{"level":2,"title":"./bin/openapi","slug":"bin-openapi"},{"level":2,"title":"Using PHP","slug":"using-php"}],"relativePath":"guide/generating-openapi-documents.md"}',t={},p=e("",12),o=[p];function c(i,l,r,u,d,k){return s(),n("div",null,o)}var g=a(t,[["render",c]]);export{m as __pageData,g as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as a,a as o}from"./app.3ef9e972.js";const m='{"title":"What is Swagger-PHP?","description":"","frontmatter":{},"headers":[],"relativePath":"guide/index.md"}',n={},s=o('<h1 id="what-is-swagger-php" tabindex="-1">What is Swagger-PHP? <a class="header-anchor" href="#what-is-swagger-php" aria-hidden="true">#</a></h1><p><code>swagger-php</code> is a library that extracts API metadata from your PHP source code files.</p><p>The idea is to add <code>swagger-php</code> <a href="./annotations.html">annotations</a> or <a href="./attributes.html">attributes</a> next to the relevant PHP code in your application. These will contain the details about your API and <code>swagger-php</code> will convert those into machine-readable <a href="https://spec.openapis.org/oas/v3.1.0.html" target="_blank" rel="noopener noreferrer">OpenAPI documentation</a>.</p><p>By adding your API documentation next to the corresponding source code (same file!) makes it easy to keep it up-to-date as all details can be modified in one place.</p><div class="tip custom-block"><p class="custom-block-title">Annotating vs. Annotations</p><p>When talking about annotating your code we mean the act of adding meta-data to your codebase. This can be done by either adding <a href="./annotations.html"><code>Annotations</code></a> or <a href="./attributes.html"><code>Attributes</code></a>.</p></div><div class="warning custom-block"><p class="custom-block-title">Requirements</p><p>Using <code>swagger-php</code> requires a minimum of <strong>PHP\xA07.2</strong> for using annotations and at least <strong>PHP\xA08.1</strong> to use attributes.</p></div>',6),i=[s];function r(c,d,p,h,l,g){return a(),t("div",null,i)}var _=e(n,[["render",r]]);export{m as __pageData,_ as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as a,a as o}from"./app.3ef9e972.js";const m='{"title":"What is Swagger-PHP?","description":"","frontmatter":{},"headers":[],"relativePath":"guide/index.md"}',n={},s=o("",6),i=[s];function r(c,d,p,h,l,g){return a(),t("div",null,i)}var _=e(n,[["render",r]]);export{m as __pageData,_ as default};
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
import{_ as e,c as a,o,a as t}from"./app.3ef9e972.js";const u='{"title":"Installation","description":"","frontmatter":{},"headers":[{"level":2,"title":"Per project","slug":"per-project"},{"level":2,"title":"Globally","slug":"globally"}],"relativePath":"guide/installation.md"}',r={},l=t(`<h1 id="installation" tabindex="-1">Installation <a class="header-anchor" href="#installation" aria-hidden="true">#</a></h1><h2 id="per-project" tabindex="-1">Per project <a class="header-anchor" href="#per-project" aria-hidden="true">#</a></h2><p>We recommend adding <code>swagger-php</code> to your project using <a href="https://getcomposer.org" target="_blank" rel="noopener noreferrer">Composer</a></p><div class="language-shell"><pre><code><span class="token operator">></span> <span class="token function">composer</span> require zircote/swagger-php
|
||||
</code></pre></div><h2 id="globally" tabindex="-1">Globally <a class="header-anchor" href="#globally" aria-hidden="true">#</a></h2><p>Alternatively, use the composer <code>global</code> argument to install <code>swagger-php</code> globally.</p><div class="language-shell"><pre><code><span class="token operator">></span> <span class="token function">composer</span> global require zircote/swagger-php
|
||||
</code></pre></div><div class="warning custom-block"><p class="custom-block-title">PATH variables</p><p>Remember to add the <code>~/.composer/vendor/bin</code> directory to the PATH in your environment.</p></div>`,8),s=[l];function n(c,i,p,d,h,g){return o(),a("div",null,s)}var m=e(r,[["render",n]]);export{u as __pageData,m as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as a,o,a as t}from"./app.3ef9e972.js";const u='{"title":"Installation","description":"","frontmatter":{},"headers":[{"level":2,"title":"Per project","slug":"per-project"},{"level":2,"title":"Globally","slug":"globally"}],"relativePath":"guide/installation.md"}',r={},l=t("",8),s=[l];function n(c,i,p,d,h,g){return o(),a("div",null,s)}var m=e(r,[["render",n]]);export{u as __pageData,m as default};
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as a,o as t,a as o}from"./app.3ef9e972.js";const u='{"title":"Migrating to v3","description":"","frontmatter":{},"headers":[{"level":2,"title":"The default output changed from json to yaml","slug":"the-default-output-changed-from-json-to-yaml"},{"level":2,"title":"Updated CLI","slug":"updated-cli"},{"level":2,"title":"Changed annotations","slug":"changed-annotations"},{"level":3,"title":"SWG is renamed to OA","slug":"swg-is-renamed-to-oa"},{"level":3,"title":"@SWG\\\\Swagger() is renamed to @OA\\\\OpenApi()","slug":"swg-swagger-is-renamed-to-oa-openapi"},{"level":3,"title":"@SWG\\\\Path() is renamed to @OA\\\\PathItem()","slug":"swg-path-is-renamed-to-oa-pathitem"},{"level":3,"title":"@SWG\\\\Definition() is removed","slug":"swg-definition-is-removed"},{"level":3,"title":"@SWG\\\\Path is removed","slug":"swg-path-is-removed"},{"level":3,"title":"Consumes, produces field is removed from OpenAPI specification","slug":"consumes-produces-field-is-removed-from-openapi-specification"},{"level":3,"title":"Rename parameter references","slug":"rename-parameter-references"},{"level":3,"title":"Rename response references","slug":"rename-response-references"},{"level":3,"title":"Renamed cli","slug":"renamed-cli"},{"level":3,"title":"More details about differences:","slug":"more-details-about-differences"}],"relativePath":"guide/migrating-to-v3.md"}',r={},i=o("",27),n=[i];function s(d,h,l,c,p,m){return t(),a("div",null,n)}var g=e(r,[["render",s]]);export{u as __pageData,g as default};
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
import{_ as a,c as n,o as s,a as e}from"./app.3ef9e972.js";const m='{"title":"Migrating to v4","description":"","frontmatter":{},"headers":[{"level":2,"title":"Overview","slug":"overview"},{"level":2,"title":"Annotations as PHP attributes","slug":"annotations-as-php-attributes"},{"level":3,"title":"Using annotations","slug":"using-annotations"},{"level":3,"title":"Using attributes","slug":"using-attributes"},{"level":2,"title":"Optional nesting","slug":"optional-nesting"},{"level":2,"title":"Annotations must be associated with a structural element","slug":"annotations-must-be-associated-with-a-structural-element"},{"level":2,"title":"The PathParameter annotation","slug":"the-pathparameter-annotation"},{"level":2,"title":"The Attachable annotation","slug":"the-attachable-annotation"},{"level":2,"title":"Removed deprecated elements","slug":"removed-deprecated-elements"},{"level":3,"title":"\\\\Openapi\\\\Analysis::processors()","slug":"openapi-analysis-processors"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$whitelist","slug":"openapi-analyser-whitelist"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$defaultImports","slug":"openapi-analyser-defaultimports"},{"level":3,"title":"\\\\Openapi\\\\Logger","slug":"openapi-logger"},{"level":2,"title":"Improvements to the Generator class","slug":"improvements-to-the-generator-class"}],"relativePath":"guide/migrating-to-v4.md"}',t={},o=e(`<h1 id="migrating-to-v4" tabindex="-1">Migrating to v4 <a class="header-anchor" href="#migrating-to-v4" aria-hidden="true">#</a></h1><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-hidden="true">#</a></h2><ul><li>As of PHP 8.1 annotations may be used as <a href="https://www.php.net/manual/en/language.attributes.overview.php" target="_blank" rel="noopener noreferrer">PHP attributes</a> instead. That means all references to annotations in this document also apply to attributes.</li><li>Annotations now <strong>must be</strong> associated with a structural element (class, trait, interface), a method, property or const.</li><li>A new annotation <code>PathParameter</code> was added for improved framework support.</li><li>A new annotation <code>Attachable</code> was added to simplify custom processing. <code>Attachable</code> can be used to attach arbitrary data to any given annotation.</li><li>Deprecated elements have been removed <ul><li><code>\\Openapi\\Analysis::processors()</code></li><li><code>\\Openapi\\Analyser::$whitelist</code></li><li><code>\\Openapi\\Analyser::$defaultImports</code></li><li><code>\\Openapi\\Logger</code></li></ul></li><li>Legacy support is available via the previous <code>TokenAnalyser</code></li><li>Improvements to the <code>Generator</code> class</li></ul><h2 id="annotations-as-php-attributes" tabindex="-1">Annotations as PHP attributes <a class="header-anchor" href="#annotations-as-php-attributes" aria-hidden="true">#</a></h2><p>While PHP attributes have been around since PHP 8.0 they were lacking the ability to be nested. This changes with PHP 8.1 which allows to use <code>new</code> in initializers.</p><p>Swagger-php attributes also make use of named arguments, so attribute parameters can be (mostly) typed. There are some limitations to type hints which can only be resolved once support for PHP 7.x is dropped.</p><h3 id="using-annotations" tabindex="-1">Using annotations <a class="header-anchor" href="#using-annotations" aria-hidden="true">#</a></h3><div class="language-php"><pre><code>
|
||||
<span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Annotations</span> <span class="token keyword">as</span> <span class="token constant">OA</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">/**
|
||||
* @OA\\Info(
|
||||
* version="1.0.0",
|
||||
* title="My API",
|
||||
* @OA\\License(name="MIT"),
|
||||
* @OA\\Attachable()
|
||||
* )
|
||||
*/</span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">OpenApiSpec</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><h3 id="using-attributes" tabindex="-1">Using attributes <a class="header-anchor" href="#using-attributes" aria-hidden="true">#</a></h3><div class="language-php"><pre><code>
|
||||
<span class="token keyword">use</span> <span class="token package">OpenApi<span class="token punctuation">\\</span>Attributes</span> <span class="token keyword">as</span> <span class="token constant">OA</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Info</span><span class="token punctuation">(</span>
|
||||
<span class="token attribute-class-name class-name">version</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'1.0.0'</span><span class="token punctuation">,</span>
|
||||
<span class="token attribute-class-name class-name">title</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'My API'</span><span class="token punctuation">,</span>
|
||||
<span class="token attribute-class-name class-name">attachables</span><span class="token punctuation">:</span> <span class="token punctuation">[</span><span class="token attribute-class-name class-name">new</span> <span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Attachable</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">]</span>
|
||||
<span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>License</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">name</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'MIT'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">class</span> <span class="token class-name-definition class-name">OpenApiSpec</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><h2 id="optional-nesting" tabindex="-1">Optional nesting <a class="header-anchor" href="#optional-nesting" aria-hidden="true">#</a></h2><p>One of the few differences between annotations and attributes visible in the above example is that the <code>OA\\License</code> attribute is not nested within <code>OA\\Info</code>. Nesting of attributes is possible and required in certain cases however, <strong>in cases where there is no ambiguity attributes may be all written on the top level</strong> and swagger-php will do the rest.</p><h2 id="annotations-must-be-associated-with-a-structural-element" tabindex="-1">Annotations must be associated with a structural element <a class="header-anchor" href="#annotations-must-be-associated-with-a-structural-element" aria-hidden="true">#</a></h2><p>The (now legacy) way of parsing PHP files meant that docblocks could live in a file without a single line of actual PHP code.</p><p>PHP Attributes cannot exist in isolation; they need code to be associated with and then are available via reflection on the associated structural element. In order to allow to keep supporting annotations and the code simple it made sense to treat annotations and attributes the same in this respect.</p><h2 id="the-pathparameter-annotation" tabindex="-1">The <code>PathParameter</code> annotation <a class="header-anchor" href="#the-pathparameter-annotation" aria-hidden="true">#</a></h2><p>As annotation this is just a short form for</p><div class="language-php"><pre><code> @<span class="token constant">OA</span><span class="token function"><span class="token punctuation">\\</span>Parameter</span><span class="token punctuation">(</span>in<span class="token operator">=</span><span class="token string single-quoted-string">'body'</span><span class="token punctuation">)</span>
|
||||
</code></pre></div><p>Things get more interesting when it comes to using it as attribute, though. In the context of a controller you can now do something like</p><div class="language-php"><pre><code><span class="token keyword">class</span> <span class="token class-name-definition class-name">MyController</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>Get</span><span class="token punctuation">(</span><span class="token attribute-class-name class-name">path</span><span class="token punctuation">:</span> <span class="token string single-quoted-string">'/products/{product_id}'</span><span class="token punctuation">)</span></span><span class="token delimiter punctuation">]</span></span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">getProduct</span><span class="token punctuation">(</span>
|
||||
<span class="token attribute"><span class="token delimiter punctuation">#[</span><span class="token attribute-content"><span class="token attribute-class-name class-name class-name-fully-qualified">OA<span class="token punctuation">\\</span>PathParameter</span></span><span class="token delimiter punctuation">]</span></span> <span class="token keyword type-declaration">string</span> <span class="token variable">$product_id</span><span class="token punctuation">)</span>
|
||||
<span class="token punctuation">{</span>
|
||||
<span class="token punctuation">}</span>
|
||||
<span class="token punctuation">}</span>
|
||||
</code></pre></div><p>Here it avoids having to duplicate details about the <code>$product_id</code> parameter and the simple use of the attribute will pick up typehints automatically.</p><h2 id="the-attachable-annotation" tabindex="-1">The <code>Attachable</code> annotation <a class="header-anchor" href="#the-attachable-annotation" aria-hidden="true">#</a></h2><p>Technically these were added in version 3.3.0, however they become really useful only with version 4.</p><p>The attachable annotation is similar to the OpenApi vendor extension <code>x=</code>. The main difference are that</p><ol><li>Attachables allow complex structures and strong typing</li><li><strong>Attachables are not added to the generated spec.</strong></li></ol><p>Their main purpose is to make customizing swagger-php easier by allowing to add arbitrary data to any annotation.</p><p>One possible use case could be custom annotations. Classes extending <code>Attachable</code> are allowed to limit the allowed parent annotations. This means it would be easy to create a new attribute to flag certain endpoints as private and exclude them under certain conditions from the spec (via a custom processor).</p><h2 id="removed-deprecated-elements" tabindex="-1">Removed deprecated elements <a class="header-anchor" href="#removed-deprecated-elements" aria-hidden="true">#</a></h2><h3 id="openapi-analysis-processors" tabindex="-1"><code>\\Openapi\\Analysis::processors()</code> <a class="header-anchor" href="#openapi-analysis-processors" aria-hidden="true">#</a></h3><p>Processors have been moved into the <code>Generator</code> class incl. some new convenience methods.</p><h3 id="openapi-analyser-whitelist" tabindex="-1"><code>\\Openapi\\Analyser::$whitelist</code> <a class="header-anchor" href="#openapi-analyser-whitelist" aria-hidden="true">#</a></h3><p>This has been replaced with the <code>Generator</code> <code>namespaces</code> property.</p><h3 id="openapi-analyser-defaultimports" tabindex="-1"><code>\\Openapi\\Analyser::$defaultImports</code> <a class="header-anchor" href="#openapi-analyser-defaultimports" aria-hidden="true">#</a></h3><p>This has been replaced with the <code>Generator</code> <code>aliases</code> property.</p><h3 id="openapi-logger" tabindex="-1"><code>\\Openapi\\Logger</code> <a class="header-anchor" href="#openapi-logger" aria-hidden="true">#</a></h3><p>This class has been removed completely. Instead, you may configure a <a href="https://www.php-fig.org/psr/psr-3/" target="_blank" rel="noopener noreferrer">PSR-3 logger</a>.</p><h2 id="improvements-to-the-generator-class" tabindex="-1">Improvements to the <code>Generator</code> class <a class="header-anchor" href="#improvements-to-the-generator-class" aria-hidden="true">#</a></h2><p>The removal of deprecated static config options means that the <code>Generator</code> class now is the main entry point into swagger-php when used programmatically.</p><p>To make the migration as simple as possible a new <code>Generator::withContext(callable)</code> has been added. This allows to use parts of the library (an <code>Analyser</code> instance, for example) within the context of a <code>Generator</code> instance.</p><p>Example:</p><div class="language-php"><pre><code><span class="token variable">$analyser</span> <span class="token operator">=</span> <span class="token function">createMyAnalyser</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$analysis</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">Generator</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">addAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'fo'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'My\\\\Attribute\\\\Namespace'</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">addNamespace</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'Other\\\\Annotations\\\\'</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">withContext</span><span class="token punctuation">(</span><span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token class-name type-declaration">Generator</span> <span class="token variable">$generator</span><span class="token punctuation">,</span> <span class="token class-name type-declaration">Analysis</span> <span class="token variable">$analysis</span><span class="token punctuation">,</span> <span class="token class-name type-declaration">Context</span> <span class="token variable">$context</span><span class="token punctuation">)</span> <span class="token keyword">use</span> <span class="token punctuation">(</span><span class="token variable">$analyser</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
<span class="token variable">$analyser</span><span class="token operator">-></span><span class="token function">setGenerator</span><span class="token punctuation">(</span><span class="token variable">$generator</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token variable">$analysis</span> <span class="token operator">=</span> <span class="token variable">$analyser</span><span class="token operator">-></span><span class="token function">fromFile</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'my_code.php'</span><span class="token punctuation">,</span> <span class="token variable">$context</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token variable">$analysis</span><span class="token operator">-></span><span class="token function">process</span><span class="token punctuation">(</span><span class="token variable">$generator</span><span class="token operator">-></span><span class="token function">getProcessors</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">return</span> <span class="token variable">$analysis</span><span class="token punctuation">;</span>
|
||||
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</code></pre></div>`,41),p=[o];function i(c,l,r,u,d,h){return s(),n("div",null,p)}var g=a(t,[["render",i]]);export{m as __pageData,g as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as a,c as n,o as s,a as e}from"./app.3ef9e972.js";const m='{"title":"Migrating to v4","description":"","frontmatter":{},"headers":[{"level":2,"title":"Overview","slug":"overview"},{"level":2,"title":"Annotations as PHP attributes","slug":"annotations-as-php-attributes"},{"level":3,"title":"Using annotations","slug":"using-annotations"},{"level":3,"title":"Using attributes","slug":"using-attributes"},{"level":2,"title":"Optional nesting","slug":"optional-nesting"},{"level":2,"title":"Annotations must be associated with a structural element","slug":"annotations-must-be-associated-with-a-structural-element"},{"level":2,"title":"The PathParameter annotation","slug":"the-pathparameter-annotation"},{"level":2,"title":"The Attachable annotation","slug":"the-attachable-annotation"},{"level":2,"title":"Removed deprecated elements","slug":"removed-deprecated-elements"},{"level":3,"title":"\\\\Openapi\\\\Analysis::processors()","slug":"openapi-analysis-processors"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$whitelist","slug":"openapi-analyser-whitelist"},{"level":3,"title":"\\\\Openapi\\\\Analyser::$defaultImports","slug":"openapi-analyser-defaultimports"},{"level":3,"title":"\\\\Openapi\\\\Logger","slug":"openapi-logger"},{"level":2,"title":"Improvements to the Generator class","slug":"improvements-to-the-generator-class"}],"relativePath":"guide/migrating-to-v4.md"}',t={},o=e("",41),p=[o];function i(c,l,r,u,d,h){return s(),n("div",null,p)}var g=a(t,[["render",i]]);export{m as __pageData,g as default};
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
import{_ as o,c,b as p,w as a,a as t,r as i,o as l,d as n,e as s}from"./app.3ef9e972.js";const O='{"title":"Required elements","description":"","frontmatter":{},"headers":[{"level":2,"title":"Minimum required annotations","slug":"minimum-required-annotations"},{"level":2,"title":"Optional elements","slug":"optional-elements"}],"relativePath":"guide/required-elements.md"}',u={},r=t('<h1 id="required-elements" tabindex="-1">Required elements <a class="header-anchor" href="#required-elements" aria-hidden="true">#</a></h1><p>The OpenAPI specification defines a minimum set of information for a valid document.</p><p>For the most part that consists of some general information about the API like <code>name</code>, <code>version</code> and at least one endpoint.</p><p>The endpoint, in turn, needs to have a path and at least one response.</p><h2 id="minimum-required-annotations" tabindex="-1">Minimum required annotations <a class="header-anchor" href="#minimum-required-annotations" aria-hidden="true">#</a></h2><p>With the above in mind a minimal API with a single endpoint could look like this</p>',6),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Annotations")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Info(
|
||||
* title="My First API",
|
||||
* version="0.1"
|
||||
* )
|
||||
*/`),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"MyController"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Get(
|
||||
* path="/api/data.json",
|
||||
* @OA\\Response(
|
||||
* response="200",
|
||||
* description="The data"
|
||||
* )
|
||||
* )
|
||||
*/`),s(`
|
||||
`),n("span",{class:"token keyword"},"public"),s(),n("span",{class:"token keyword"},"function"),s(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token comment"},"// ..."),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Attributes")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OA"),n("span",{class:"token punctuation"},"\\"),s("Info")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"title"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string double-quoted-string"},'"My First API"'),n("span",{class:"token punctuation"},","),s(),n("span",{class:"token attribute-class-name class-name"},"version"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string double-quoted-string"},'"0.1"'),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"MyController"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OA"),n("span",{class:"token punctuation"},"\\"),s("Get")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"path"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'/api/data.json'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OA"),n("span",{class:"token punctuation"},"\\"),s("Response")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"response"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'200'"),n("span",{class:"token punctuation"},","),s(),n("span",{class:"token attribute-class-name class-name"},"description"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'The data'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token keyword"},"public"),s(),n("span",{class:"token keyword"},"function"),s(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token comment"},"// ..."),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),m=t(`<p>with the resulting OpenAPI document like this</p><div class="language-yaml"><pre><code><span class="token key atrule">openapi</span><span class="token punctuation">:</span> 3.0.0
|
||||
<span class="token key atrule">info</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">title</span><span class="token punctuation">:</span> <span class="token string">'My First API'</span>
|
||||
<span class="token key atrule">version</span><span class="token punctuation">:</span> <span class="token string">'0.1'</span>
|
||||
<span class="token key atrule">paths</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">/api/data.json</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">get</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">operationId</span><span class="token punctuation">:</span> 236f26ae21b015a60adbce41f8f316e3
|
||||
<span class="token key atrule">responses</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">'200'</span><span class="token punctuation">:</span>
|
||||
<span class="token key atrule">description</span><span class="token punctuation">:</span> <span class="token string">'The data'</span>
|
||||
</code></pre></div><div class="warning custom-block"><p class="custom-block-title">Code locations</p><p>Attributes and annotations can be added anywhere on declarations in code as defined by the PHP docs. These are limited to the extent of what the PHP Reflection APIs supports.</p></div><h2 id="optional-elements" tabindex="-1">Optional elements <a class="header-anchor" href="#optional-elements" aria-hidden="true">#</a></h2><p>Looking at the generated document you will notice that there are some elements that <code>swagger-php</code> adds automatically when they are missing.</p><p>For the most part those are <code>@OA\\OpenApi</code>, <code>@OA\\Components</code> and <code>@OA\\PathItem</code>.</p>`,6);function h(_,f,g,y,b,A){const e=i("codeblock");return l(),c("div",null,[r,p(e,{id:"minimal"},{an:a(()=>[k]),at:a(()=>[d]),_:1}),m])}var q=o(u,[["render",h]]);export{O as __pageData,q as default};
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
import{_ as o,c,b as p,w as a,a as t,r as i,o as l,d as n,e as s}from"./app.3ef9e972.js";const O='{"title":"Required elements","description":"","frontmatter":{},"headers":[{"level":2,"title":"Minimum required annotations","slug":"minimum-required-annotations"},{"level":2,"title":"Optional elements","slug":"optional-elements"}],"relativePath":"guide/required-elements.md"}',u={},r=t("",6),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Annotations")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Info(
|
||||
* title="My First API",
|
||||
* version="0.1"
|
||||
* )
|
||||
*/`),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"MyController"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Get(
|
||||
* path="/api/data.json",
|
||||
* @OA\\Response(
|
||||
* response="200",
|
||||
* description="The data"
|
||||
* )
|
||||
* )
|
||||
*/`),s(`
|
||||
`),n("span",{class:"token keyword"},"public"),s(),n("span",{class:"token keyword"},"function"),s(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token comment"},"// ..."),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),s(),n("span",{class:"token package"},[s("OpenApi"),n("span",{class:"token punctuation"},"\\"),s("Attributes")]),s(),n("span",{class:"token keyword"},"as"),s(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),s(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OA"),n("span",{class:"token punctuation"},"\\"),s("Info")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"title"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string double-quoted-string"},'"My First API"'),n("span",{class:"token punctuation"},","),s(),n("span",{class:"token attribute-class-name class-name"},"version"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string double-quoted-string"},'"0.1"'),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"MyController"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OA"),n("span",{class:"token punctuation"},"\\"),s("Get")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"path"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'/api/data.json'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[s("OA"),n("span",{class:"token punctuation"},"\\"),s("Response")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"response"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'200'"),n("span",{class:"token punctuation"},","),s(),n("span",{class:"token attribute-class-name class-name"},"description"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string single-quoted-string"},"'The data'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),s(`
|
||||
`),n("span",{class:"token keyword"},"public"),s(),n("span",{class:"token keyword"},"function"),s(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token comment"},"// ..."),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),s(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),s(`
|
||||
`),n("span",{class:"token punctuation"},"{"),s(`
|
||||
`),n("span",{class:"token punctuation"},"}"),s(`
|
||||
`)])])])],-1),m=t("",6);function h(_,f,g,y,b,A){const e=i("codeblock");return l(),c("div",null,[r,p(e,{id:"minimal"},{an:a(()=>[k]),at:a(()=>[d]),_:1}),m])}var q=o(u,[["render",h]]);export{O as __pageData,q as default};
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
import{_ as e,c as t,o as a,a as o}from"./app.3ef9e972.js";const g='{"title":"Under the hood","description":"","frontmatter":{},"headers":[{"level":2,"title":"Processing flow","slug":"processing-flow"},{"level":2,"title":"Context","slug":"context"},{"level":2,"title":"Analysis","slug":"analysis"},{"level":2,"title":"Documentation","slug":"documentation"},{"level":3,"title":"Installation","slug":"installation"},{"level":3,"title":"Workflow","slug":"workflow"}],"relativePath":"guide/under-the-hood.md"}',n={},i=o(`<h1 id="under-the-hood" tabindex="-1">Under the hood <a class="header-anchor" href="#under-the-hood" aria-hidden="true">#</a></h1><h2 id="processing-flow" tabindex="-1">Processing flow <a class="header-anchor" href="#processing-flow" aria-hidden="true">#</a></h2><ul><li>The <code>Generator</code> iterates over the given sources (Symfony <code>Finder</code>, file/directory list, etc)</li><li>The configured analyser (<code>AnalyserInterface</code>) reads the files and builds an <code>Analysis</code> object. Default (as of v4) is the <code>ReflectionAnalyser</code>. Alternatively, there is the <code>TokenAnalyser</code> which was the default in v3.</li><li>The <code>Analysis</code> object and its annotations are then processed by the configured processors.</li><li>If enabled, the analysis/annotations are validated.</li><li>The root <code>OpenApi</code> annotation then contains all annotations and is serialized into YAML/JSON.</li></ul><h2 id="context" tabindex="-1"><code>Context</code> <a class="header-anchor" href="#context" aria-hidden="true">#</a></h2><p>Each annotation is associated with a unique <code>Context</code> instance. This contains details, collected by the parser/analyser, about the PHP context where the annotation was found.</p><p>Typically, there will be a processor that uses the data to augment/enrich the annotation.</p><p><strong>Examples of the data collected:</strong></p><ul><li>class/interface/trait/enum names</li><li>property names</li><li>doctype or native type hints</li><li>file name and line number</li></ul><h2 id="analysis" tabindex="-1">Analysis <a class="header-anchor" href="#analysis" aria-hidden="true">#</a></h2><p>Contains all detected annotations and other relevant meta-data.</p><p>It uses a <code>SplObjectStorage</code> instance to store the parsed annotations.</p><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-hidden="true">#</a></h2><p>This documentation is generated with <a href="https://vitepress.vuejs.org/" target="_blank" rel="noopener noreferrer">VitePress</a></p><h3 id="installation" tabindex="-1">Installation <a class="header-anchor" href="#installation" aria-hidden="true">#</a></h3><div class="language-shell"><pre><code><span class="token builtin class-name">cd</span> docs
|
||||
<span class="token function">npm</span> <span class="token function">install</span> vitepress
|
||||
</code></pre></div><h3 id="workflow" tabindex="-1">Workflow <a class="header-anchor" href="#workflow" aria-hidden="true">#</a></h3><ul><li>Edit <code>.md</code> files in the <code>docs</code> folder</li><li>Update annotation / attribute PHP docblocks.<br>These will be extracted during publishing into the <a href="./../reference/">reference</a> section.</li><li>Run 'composer docs:build' to check for any errors</li><li>Run 'composer docs:dev' to test the generated documentation locally (<code>localhost:3000</code>)</li><li>Create PR and update <code>master</code></li><li>Manually trigger the <code>gh-pages</code> workflow to update the online docs.</li></ul><p>The last step requires commit rights on <code>zircote/swagger-php</code>.</p>`,18),s=[i];function l(r,d,c,h,u,p){return a(),t("div",null,s)}var m=e(n,[["render",l]]);export{g as __pageData,m as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as a,a as o}from"./app.3ef9e972.js";const g='{"title":"Under the hood","description":"","frontmatter":{},"headers":[{"level":2,"title":"Processing flow","slug":"processing-flow"},{"level":2,"title":"Context","slug":"context"},{"level":2,"title":"Analysis","slug":"analysis"},{"level":2,"title":"Documentation","slug":"documentation"},{"level":3,"title":"Installation","slug":"installation"},{"level":3,"title":"Workflow","slug":"workflow"}],"relativePath":"guide/under-the-hood.md"}',n={},i=o("",18),s=[i];function l(r,d,c,h,u,p){return a(),t("div",null,s)}var m=e(n,[["render",l]]);export{g as __pageData,m as default};
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
import{_ as o,c,b as i,w as a,a as s,r as p,o as l,d as n,e}from"./app.3ef9e972.js";const x='{"title":"Home","description":"","frontmatter":{"home":true,"actionText":"User Guide \u2192","actionLink":"/guide/","features":[{"title":"OpenAPI conformant","details":"Generate OpenAPI documents in version 3.0 or 3.1."},{"title":"Document your API inside PHP source code","details":"Using swagger-php lets you write the API documentation inside the PHP source files which helps keeping the documentation up-to-date."},{"title":"Annotation and Attribute support","details":"Annotations can be either docblocks or PHP 8.1 attributes."}]},"headers":[{"level":3,"title":"1. Install with composer:","slug":"_1-install-with-composer"},{"level":3,"title":"2. Update your code","slug":"_2-update-your-code"},{"level":3,"title":"3. Generate OpenAPI documentation","slug":"_3-generate-openapi-documentation"},{"level":3,"title":"4. Explore and interact with your API","slug":"_4-explore-and-interact-with-your-api"},{"level":2,"title":"Links","slug":"links"}],"relativePath":"index.md"}',r={},u=s(`<h3 id="_1-install-with-composer" tabindex="-1">1. Install with composer: <a class="header-anchor" href="#_1-install-with-composer" aria-hidden="true">#</a></h3><div class="language-shell"><pre><code><span class="token operator">></span> <span class="token function">composer</span> require zircote/swagger-php
|
||||
</code></pre></div><h3 id="_2-update-your-code" tabindex="-1">2. Update your code <a class="header-anchor" href="#_2-update-your-code" aria-hidden="true">#</a></h3><p>Add <code>swagger-php</code> annotations or attributes to your source code.</p>`,4),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),e(),n("span",{class:"token package"},[e("OpenApi"),n("span",{class:"token punctuation"},"\\"),e("Annotations")]),e(),n("span",{class:"token keyword"},"as"),e(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),e(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Info(
|
||||
* title="My First API",
|
||||
* version="0.1"
|
||||
* )
|
||||
*/`),e(`
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"MyController"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Get(
|
||||
* path="/api/data.json",
|
||||
* @OA\\Response(
|
||||
* response="200",
|
||||
* description="The data"
|
||||
* )
|
||||
* )
|
||||
*/`),e(`
|
||||
`),n("span",{class:"token keyword"},"public"),e(),n("span",{class:"token keyword"},"function"),e(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token comment"},"// ..."),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`)])])])],-1),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),e(),n("span",{class:"token package"},[e("OpenApi"),n("span",{class:"token punctuation"},"\\"),e("Attributes")]),e(),n("span",{class:"token keyword"},"as"),e(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),e(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[e("OA"),n("span",{class:"token punctuation"},"\\"),e("Info")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"title"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string double-quoted-string"},'"My First API"'),n("span",{class:"token punctuation"},","),e(),n("span",{class:"token attribute-class-name class-name"},"version"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string double-quoted-string"},'"0.1"'),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),e(`
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"MyController"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[e("OA"),n("span",{class:"token punctuation"},"\\"),e("Get")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"path"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string single-quoted-string"},"'/api/data.json'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),e(`
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[e("OA"),n("span",{class:"token punctuation"},"\\"),e("Response")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"response"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string single-quoted-string"},"'200'"),n("span",{class:"token punctuation"},","),e(),n("span",{class:"token attribute-class-name class-name"},"description"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string single-quoted-string"},"'The data'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),e(`
|
||||
`),n("span",{class:"token keyword"},"public"),e(),n("span",{class:"token keyword"},"function"),e(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token comment"},"// ..."),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`)])])])],-1),h=s(`<h3 id="_3-generate-openapi-documentation" tabindex="-1">3. Generate OpenAPI documentation <a class="header-anchor" href="#_3-generate-openapi-documentation" aria-hidden="true">#</a></h3><div class="language-shell"><pre><code><span class="token operator">></span> ./bin/openapi src <span class="token parameter variable">-o</span> openapi.yaml
|
||||
</code></pre></div><h3 id="_4-explore-and-interact-with-your-api" tabindex="-1">4. Explore and interact with your API <a class="header-anchor" href="#_4-explore-and-interact-with-your-api" aria-hidden="true">#</a></h3><p>Use an OpenAPI tool like <a href="https://swagger.io/tools/swagger-ui/" target="_blank" rel="noopener noreferrer">Swagger UI </a> to explore and interact with your API.</p><h2 id="links" tabindex="-1">Links <a class="header-anchor" href="#links" aria-hidden="true">#</a></h2><ul><li><a href="./guide/">User Guide</a></li><li><a href="./reference/">Reference</a></li><li><a href="https://learn.openapis.org/" target="_blank" rel="noopener noreferrer">OpenApi Documentation</a></li><li><a href="https://spec.openapis.org/oas/v3.1.0.html" target="_blank" rel="noopener noreferrer">OpenApi Specification</a></li><li><a href="https://github.com/zircote/swagger-php/tree/master/Examples" target="_blank" rel="noopener noreferrer">Learn by example</a></li><li><a href="./related-projects.html">Related projects</a></li><li><a href="https://github.com/zircote/swagger-php/tree/2.x/docs" target="_blank" rel="noopener noreferrer">Swagger-php 2.x documentation</a></li></ul>`,6);function m(g,_,f,b,A,w){const t=p("codeblock");return l(),c("div",null,[u,i(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),h])}var P=o(r,[["render",m]]);export{x as __pageData,P as default};
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
import{_ as o,c,b as i,w as a,a as s,r as p,o as l,d as n,e}from"./app.3ef9e972.js";const x='{"title":"Home","description":"","frontmatter":{"home":true,"actionText":"User Guide \u2192","actionLink":"/guide/","features":[{"title":"OpenAPI conformant","details":"Generate OpenAPI documents in version 3.0 or 3.1."},{"title":"Document your API inside PHP source code","details":"Using swagger-php lets you write the API documentation inside the PHP source files which helps keeping the documentation up-to-date."},{"title":"Annotation and Attribute support","details":"Annotations can be either docblocks or PHP 8.1 attributes."}]},"headers":[{"level":3,"title":"1. Install with composer:","slug":"_1-install-with-composer"},{"level":3,"title":"2. Update your code","slug":"_2-update-your-code"},{"level":3,"title":"3. Generate OpenAPI documentation","slug":"_3-generate-openapi-documentation"},{"level":3,"title":"4. Explore and interact with your API","slug":"_4-explore-and-interact-with-your-api"},{"level":2,"title":"Links","slug":"links"}],"relativePath":"index.md"}',r={},u=s("",4),d=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),e(),n("span",{class:"token package"},[e("OpenApi"),n("span",{class:"token punctuation"},"\\"),e("Annotations")]),e(),n("span",{class:"token keyword"},"as"),e(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),e(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Info(
|
||||
* title="My First API",
|
||||
* version="0.1"
|
||||
* )
|
||||
*/`),e(`
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"MyController"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
|
||||
`),n("span",{class:"token comment"},`/**
|
||||
* @OA\\Get(
|
||||
* path="/api/data.json",
|
||||
* @OA\\Response(
|
||||
* response="200",
|
||||
* description="The data"
|
||||
* )
|
||||
* )
|
||||
*/`),e(`
|
||||
`),n("span",{class:"token keyword"},"public"),e(),n("span",{class:"token keyword"},"function"),e(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token comment"},"// ..."),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`)])])])],-1),k=n("div",{class:"language-php"},[n("pre",null,[n("code",null,[n("span",{class:"token php language-php"},[n("span",{class:"token delimiter important"},"<?php"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"use"),e(),n("span",{class:"token package"},[e("OpenApi"),n("span",{class:"token punctuation"},"\\"),e("Attributes")]),e(),n("span",{class:"token keyword"},"as"),e(),n("span",{class:"token constant"},"OA"),n("span",{class:"token punctuation"},";"),e(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[e("OA"),n("span",{class:"token punctuation"},"\\"),e("Info")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"title"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string double-quoted-string"},'"My First API"'),n("span",{class:"token punctuation"},","),e(),n("span",{class:"token attribute-class-name class-name"},"version"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string double-quoted-string"},'"0.1"'),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),e(`
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"OpenApi"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"MyController"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[e("OA"),n("span",{class:"token punctuation"},"\\"),e("Get")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"path"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string single-quoted-string"},"'/api/data.json'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),e(`
|
||||
`),n("span",{class:"token attribute"},[n("span",{class:"token delimiter punctuation"},"#["),n("span",{class:"token attribute-content"},[n("span",{class:"token attribute-class-name class-name class-name-fully-qualified"},[e("OA"),n("span",{class:"token punctuation"},"\\"),e("Response")]),n("span",{class:"token punctuation"},"("),n("span",{class:"token attribute-class-name class-name"},"response"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string single-quoted-string"},"'200'"),n("span",{class:"token punctuation"},","),e(),n("span",{class:"token attribute-class-name class-name"},"description"),n("span",{class:"token punctuation"},":"),e(),n("span",{class:"token string single-quoted-string"},"'The data'"),n("span",{class:"token punctuation"},")")]),n("span",{class:"token delimiter punctuation"},"]")]),e(`
|
||||
`),n("span",{class:"token keyword"},"public"),e(),n("span",{class:"token keyword"},"function"),e(),n("span",{class:"token function-definition function"},"getResource"),n("span",{class:"token punctuation"},"("),n("span",{class:"token punctuation"},")"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token comment"},"// ..."),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
|
||||
`),n("span",{class:"token keyword"},"class"),e(),n("span",{class:"token class-name-definition class-name"},"OpenApiSpec"),e(`
|
||||
`),n("span",{class:"token punctuation"},"{"),e(`
|
||||
`),n("span",{class:"token punctuation"},"}"),e(`
|
||||
`)])])])],-1),h=s("",6);function m(g,_,f,b,A,w){const t=p("codeblock");return l(),c("div",null,[u,i(t,{id:"minimal"},{an:a(()=>[d]),at:a(()=>[k]),_:1}),h])}var P=o(r,[["render",m]]);export{x as __pageData,P as default};
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as a,o as t,a as r}from"./app.3ef9e972.js";const b='{"title":"Annotations","description":"","frontmatter":{},"headers":[{"level":2,"title":"AdditionalProperties","slug":"additionalproperties"},{"level":2,"title":"Attachable","slug":"attachable"},{"level":2,"title":"Components","slug":"components"},{"level":2,"title":"Contact","slug":"contact"},{"level":2,"title":"CookieParameter","slug":"cookieparameter"},{"level":2,"title":"Delete","slug":"delete"},{"level":2,"title":"Discriminator","slug":"discriminator"},{"level":2,"title":"Examples","slug":"examples"},{"level":2,"title":"ExternalDocumentation","slug":"externaldocumentation"},{"level":2,"title":"Flow","slug":"flow"},{"level":2,"title":"Get","slug":"get"},{"level":2,"title":"Head","slug":"head"},{"level":2,"title":"Header","slug":"header"},{"level":2,"title":"HeaderParameter","slug":"headerparameter"},{"level":2,"title":"Info","slug":"info"},{"level":2,"title":"Items","slug":"items"},{"level":2,"title":"JsonContent","slug":"jsoncontent"},{"level":2,"title":"License","slug":"license"},{"level":2,"title":"Link","slug":"link"},{"level":2,"title":"MediaType","slug":"mediatype"},{"level":2,"title":"OpenApi","slug":"openapi"},{"level":2,"title":"Options","slug":"options"},{"level":2,"title":"Parameter","slug":"parameter"},{"level":2,"title":"Patch","slug":"patch"},{"level":2,"title":"PathItem","slug":"pathitem"},{"level":2,"title":"PathParameter","slug":"pathparameter"},{"level":2,"title":"Post","slug":"post"},{"level":2,"title":"Property","slug":"property"},{"level":2,"title":"Put","slug":"put"},{"level":2,"title":"QueryParameter","slug":"queryparameter"},{"level":2,"title":"RequestBody","slug":"requestbody"},{"level":2,"title":"Response","slug":"response"},{"level":2,"title":"Schema","slug":"schema"},{"level":2,"title":"SecurityScheme","slug":"securityscheme"},{"level":2,"title":"Server","slug":"server"},{"level":2,"title":"ServerVariable","slug":"servervariable"},{"level":2,"title":"Tag","slug":"tag"},{"level":2,"title":"Trace","slug":"trace"},{"level":2,"title":"Webhook","slug":"webhook"},{"level":2,"title":"Xml","slug":"xml"},{"level":2,"title":"XmlContent","slug":"xmlcontent"}],"relativePath":"reference/annotations.md"}',n={},s=r("",489),o=[s];function i(d,h,p,l,c,f){return t(),a("div",null,o)}var u=e(n,[["render",i]]);export{b as __pageData,u as default};
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as a,a as n}from"./app.3ef9e972.js";const u='{"title":"Attributes","description":"","frontmatter":{},"headers":[{"level":2,"title":"AdditionalProperties","slug":"additionalproperties"},{"level":2,"title":"Attachable","slug":"attachable"},{"level":2,"title":"Components","slug":"components"},{"level":2,"title":"Contact","slug":"contact"},{"level":2,"title":"CookieParameter","slug":"cookieparameter"},{"level":2,"title":"Delete","slug":"delete"},{"level":2,"title":"Discriminator","slug":"discriminator"},{"level":2,"title":"Examples","slug":"examples"},{"level":2,"title":"ExternalDocumentation","slug":"externaldocumentation"},{"level":2,"title":"Flow","slug":"flow"},{"level":2,"title":"Get","slug":"get"},{"level":2,"title":"Head","slug":"head"},{"level":2,"title":"Header","slug":"header"},{"level":2,"title":"HeaderParameter","slug":"headerparameter"},{"level":2,"title":"Info","slug":"info"},{"level":2,"title":"Items","slug":"items"},{"level":2,"title":"JsonContent","slug":"jsoncontent"},{"level":2,"title":"License","slug":"license"},{"level":2,"title":"Link","slug":"link"},{"level":2,"title":"MediaType","slug":"mediatype"},{"level":2,"title":"OpenApi","slug":"openapi"},{"level":2,"title":"Options","slug":"options"},{"level":2,"title":"Parameter","slug":"parameter"},{"level":2,"title":"Patch","slug":"patch"},{"level":2,"title":"PathItem","slug":"pathitem"},{"level":2,"title":"PathParameter","slug":"pathparameter"},{"level":2,"title":"Post","slug":"post"},{"level":2,"title":"Property","slug":"property"},{"level":2,"title":"Put","slug":"put"},{"level":2,"title":"QueryParameter","slug":"queryparameter"},{"level":2,"title":"RequestBody","slug":"requestbody"},{"level":2,"title":"Response","slug":"response"},{"level":2,"title":"Schema","slug":"schema"},{"level":2,"title":"SecurityScheme","slug":"securityscheme"},{"level":2,"title":"Server","slug":"server"},{"level":2,"title":"ServerVariable","slug":"servervariable"},{"level":2,"title":"Tag","slug":"tag"},{"level":2,"title":"Trace","slug":"trace"},{"level":2,"title":"Webhook","slug":"webhook"},{"level":2,"title":"Xml","slug":"xml"},{"level":2,"title":"XmlContent","slug":"xmlcontent"}],"relativePath":"reference/attributes.md"}',s={},r=n("",402),o=[r];function i(d,l,p,h,c,m){return a(),t("div",null,o)}var b=e(s,[["render",i]]);export{u as __pageData,b as default};
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
import{_ as n,c as s,o as a,a as t}from"./app.3ef9e972.js";const h='{"title":"Using the Generator","description":"","frontmatter":{},"headers":[{"level":2,"title":"Introduction","slug":"introduction"},{"level":2,"title":"The \\\\OpenApi\\\\scan() function","slug":"the-openapi-scan-function"},{"level":2,"title":"The \\\\OpenApi\\\\Generator class","slug":"the-openapi-generator-class"}],"relativePath":"reference/generator.md"}',e={},p=t(`<h1 id="using-the-generator" tabindex="-1">Using the <code>Generator</code> <a class="header-anchor" href="#using-the-generator" aria-hidden="true">#</a></h1><h2 id="introduction" tabindex="-1">Introduction <a class="header-anchor" href="#introduction" aria-hidden="true">#</a></h2><p>The <code>Generator</code> class provides an object-oriented way to use <code>swagger-php</code> and all its aspects in a single place.</p><h2 id="the-openapi-scan-function" tabindex="-1">The <code>\\OpenApi\\scan()</code> function <a class="header-anchor" href="#the-openapi-scan-function" aria-hidden="true">#</a></h2><p>For a long time the <code>\\OpenApi\\scan()</code> function was the main entry point into using swagger-php from PHP code.</p><div class="language-php"><pre><code><span class="token comment">/**
|
||||
* Scan the filesystem for OpenAPI annotations and build openapi-documentation.
|
||||
*
|
||||
* @param array|Finder|string $directory The directory(s) or filename(s)
|
||||
* @param array $options
|
||||
* exclude: string|array $exclude The directory(s) or filename(s) to exclude (as absolute or relative paths)
|
||||
* pattern: string $pattern File pattern(s) to scan (default: *.php)
|
||||
* analyser: defaults to StaticAnalyser
|
||||
* analysis: defaults to a new Analysis
|
||||
* processors: defaults to the registered processors in Analysis
|
||||
*
|
||||
* @return OpenApi
|
||||
*/</span>
|
||||
<span class="token keyword">function</span> <span class="token function-definition function">scan</span><span class="token punctuation">(</span><span class="token variable">$directory</span><span class="token punctuation">,</span> <span class="token variable">$options</span> <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token comment">/* ... */</span> <span class="token punctuation">}</span>
|
||||
</code></pre></div><p>Using it looked typically something like this:</p><div class="language-php"><pre><code><span class="token keyword">require</span><span class="token punctuation">(</span><span class="token string double-quoted-string">"vendor/autoload.php"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token function"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>scan</span><span class="token punctuation">(</span><span class="token constant">__DIR__</span><span class="token punctuation">,</span> <span class="token punctuation">[</span><span class="token string single-quoted-string">'exclude'</span> <span class="token operator">=></span> <span class="token punctuation">[</span><span class="token string single-quoted-string">'tests'</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'pattern'</span> <span class="token operator">=></span> <span class="token string single-quoted-string">'*.php'</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</code></pre></div><p>The two configuration options for the underlying Doctrine doc-block parser <code>aliases</code> and <code>namespaces</code> are not part of this function and need to be set separately.</p><p>Being static this means setting them back is the callers responsibility and there is also the fact that some Doctrine configuration currently can not be reverted easily.</p><p>Therefore, having a single side effect free way of using swagger-php seemed like a good idea...</p><h2 id="the-openapi-generator-class" tabindex="-1">The <code>\\OpenApi\\Generator</code> class <a class="header-anchor" href="#the-openapi-generator-class" aria-hidden="true">#</a></h2><p>The <code>Generator</code> class can be used in object-oriented (and fluent) style which allows for easy customization if needed.</p><p>In that case to actually process the given input files the <strong>non-static</strong> method <code>generate()</code> is to be used.</p><p>Full example of using the <code>Generator</code> class to generate OpenApi specs.</p><div class="language-php"><pre><code><span class="token keyword">require</span><span class="token punctuation">(</span><span class="token string double-quoted-string">"vendor/autoload.php"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$validate</span> <span class="token operator">=</span> <span class="token constant boolean">true</span><span class="token punctuation">;</span>
|
||||
<span class="token variable">$logger</span> <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name class-name-fully-qualified"><span class="token punctuation">\\</span>Psr<span class="token punctuation">\\</span>Log<span class="token punctuation">\\</span>NullLogger</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token variable">$processors</span> <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token comment">/* my processors */</span><span class="token punctuation">]</span><span class="token punctuation">;</span>
|
||||
<span class="token variable">$finder</span> <span class="token operator">=</span> <span class="token class-name class-name-fully-qualified static-context"><span class="token punctuation">\\</span>Symfony<span class="token punctuation">\\</span>Component<span class="token punctuation">\\</span>Finder<span class="token punctuation">\\</span>Finder</span><span class="token operator">::</span><span class="token function">create</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">files</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">name</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'*.php'</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">in</span><span class="token punctuation">(</span><span class="token constant">__DIR__</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name class-name-fully-qualified"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Generator</span><span class="token punctuation">(</span><span class="token variable">$logger</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">setProcessors</span><span class="token punctuation">(</span><span class="token variable">$processors</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">setAliases</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string single-quoted-string">'MY'</span> <span class="token operator">=></span> <span class="token string single-quoted-string">'My\\Annotations'</span><span class="token punctuation">]</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">setNamespaces</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string single-quoted-string">'My\\\\Annotations\\\\'</span><span class="token punctuation">]</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">setAnalyser</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name class-name-fully-qualified"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Analysers<span class="token punctuation">\\</span>TokenAnalyser</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">setVersion</span><span class="token punctuation">(</span><span class="token class-name class-name-fully-qualified static-context"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Annotations<span class="token punctuation">\\</span>OpenApi</span><span class="token operator">::</span><span class="token constant">VERSION_3_0_0</span><span class="token punctuation">)</span>
|
||||
<span class="token operator">-></span><span class="token function">generate</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string single-quoted-string">'/path1/to/project'</span><span class="token punctuation">,</span> <span class="token variable">$finder</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token keyword">new</span> <span class="token class-name class-name-fully-qualified"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Analysis</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token variable">$validate</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</code></pre></div><p><code>Aliases</code> and <code>namespaces</code> are additional options that allow to customize the parsing of docblocks.</p><p>Defaults:</p><ul><li><p><strong>aliases</strong>: <code>['oa' => 'OpenApi\\\\Annotations']</code></p><p>Aliases help the underlying <code>doctrine annotations library</code> to parse annotations. Effectively they avoid having to write <code>use OpenApi\\Annotations as OA;</code> in your code and make <code>@OA\\property(..)</code> annotations still work.</p></li><li><p><strong>namespaces</strong>: <code>['OpenApi\\\\Annotations\\\\']</code></p><p>Namespaces control which annotation namespaces can be autoloaded automatically. Under the hood this is handled by registering a custom loader with the <code>doctrine annotation library</code>.</p></li></ul><p>Advantages:</p><ul><li>The <code>Generator</code> code will handle configuring things as before in a single place</li><li>Static settings will be reverted to the default once finished</li><li>The get/set methods allow for using type hints</li><li>Static configuration is deprecated and can be removed at some point without code changes</li><li>Build in support for PSR logger</li><li>Support for <a href="https://symfony.com/doc/current/components/finder.html" target="_blank" rel="noopener noreferrer">Symfony Finder</a>, <code>\\SplInfo</code> and file/directory names (\`string) as source.</li></ul><p>The minimum code required, using the <code>generate()</code> method, looks quite similar to the old <code>scan()</code> code:</p><div class="language-php"><pre><code> <span class="token comment">/**
|
||||
* Generate OpenAPI spec by scanning the given source files.
|
||||
*
|
||||
* @param iterable $sources PHP source files to scan.
|
||||
* Supported sources:
|
||||
* * string - file / directory name
|
||||
* * \\SplFileInfo
|
||||
* * \\Symfony\\Component\\Finder\\Finder
|
||||
* @param null|Analysis $analysis custom analysis instance
|
||||
* @param bool $validate flag to enable/disable validation of the returned spec
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function-definition function">generate</span><span class="token punctuation">(</span><span class="token keyword type-hint">iterable</span> <span class="token variable">$sources</span><span class="token punctuation">,</span> <span class="token operator">?</span><span class="token class-name type-declaration">Analysis</span> <span class="token variable">$analysis</span> <span class="token operator">=</span> <span class="token constant">null</span><span class="token punctuation">,</span> <span class="token keyword type-hint">bool</span> <span class="token variable">$validate</span> <span class="token operator">=</span> <span class="token constant boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token class-name class-name-fully-qualified return-type"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>OpenApi</span> <span class="token punctuation">{</span> <span class="token comment">/* ... */</span> <span class="token punctuation">}</span>
|
||||
</code></pre></div><div class="language-php"><pre><code><span class="token keyword">require</span><span class="token punctuation">(</span><span class="token string double-quoted-string">"vendor/autoload.php"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name class-name-fully-qualified"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Generator</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">generate</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string single-quoted-string">'/path1/to/project'</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</code></pre></div><p>For those that want to type even less and keep using a plain array to configure <code>swagger-php</code> there is also a static version:</p><div class="language-php"><pre><code><span class="token php language-php"><span class="token delimiter important"><?php</span>
|
||||
<span class="token keyword">require</span><span class="token punctuation">(</span><span class="token string double-quoted-string">"vendor/autoload.php"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token class-name class-name-fully-qualified static-context"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Generator</span><span class="token operator">::</span><span class="token function">scan</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string single-quoted-string">'/path/to/project'</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token function">header</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'Content-Type: application/x-yaml'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<span class="token keyword">echo</span> <span class="token variable">$openapi</span><span class="token operator">-></span><span class="token function">toYaml</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</span></code></pre></div><p><strong>Note:</strong> While using the same name as the old <code>scan()</code> function, the <code>Generator::scan</code> method is not 100% backwards compatible.</p><div class="language-php"><pre><code> <span class="token comment">/**
|
||||
* Static wrapper around \`Generator::generate()\`.
|
||||
*
|
||||
* @param iterable $sources PHP source files to scan.
|
||||
* Supported sources:
|
||||
* * string
|
||||
* * \\SplFileInfo
|
||||
* * \\Symfony\\Component\\Finder\\Finder
|
||||
* @param array $options
|
||||
* aliases: null|array Defaults to \`['oa' => 'OpenApi\\\\Annotations']\`.
|
||||
* namespaces: null|array Defaults to \`['OpenApi\\\\Annotations\\\\']\`.
|
||||
* analyser: null|AnalyserInterface Defaults to a new \`ReflectionAnalyser\` supporting both docblocks and attributes.
|
||||
* analysis: null|Analysis Defaults to a new \`Analysis\`.
|
||||
* processors: null|array Defaults to \`Analysis::processors()\`.
|
||||
* logger: null|\\Psr\\Log\\LoggerInterface If not set logging will use \\OpenApi\\Logger as before.
|
||||
* validate: bool Defaults to \`true\`.
|
||||
*/</span>
|
||||
<span class="token keyword">public</span> <span class="token keyword">static</span> <span class="token keyword">function</span> <span class="token function-definition function">scan</span><span class="token punctuation">(</span><span class="token keyword type-hint">iterable</span> <span class="token variable">$sources</span><span class="token punctuation">,</span> <span class="token keyword type-hint">array</span> <span class="token variable">$options</span> <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token class-name return-type">OpenApi</span> <span class="token punctuation">{</span> <span class="token comment">/* ... */</span> <span class="token punctuation">}</span>
|
||||
</code></pre></div><p>Most notably the <code>exclude</code> and <code>pattern</code> keys are no longer supported. Instead, a Symfony <code>Finder</code> instance can be passed in as source directly (same as with <code>Generator::generate()</code>).</p><p>If needed, the <code>\\OpenApi\\Util</code> class provides a builder method that allows to keep the status-quo</p><div class="language-php"><pre><code><span class="token variable">$exclude</span> <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token string single-quoted-string">'tests'</span><span class="token punctuation">]</span><span class="token punctuation">;</span>
|
||||
<span class="token variable">$pattern</span> <span class="token operator">=</span> <span class="token string single-quoted-string">'*.php'</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token class-name class-name-fully-qualified static-context"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Generator</span><span class="token operator">::</span><span class="token function">scan</span><span class="token punctuation">(</span><span class="token class-name class-name-fully-qualified static-context"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>Util</span><span class="token operator">::</span><span class="token function">finder</span><span class="token punctuation">(</span><span class="token constant">__DIR__</span><span class="token punctuation">,</span> <span class="token variable">$exclude</span><span class="token punctuation">,</span> <span class="token variable">$pattern</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token comment">// same as</span>
|
||||
|
||||
<span class="token variable">$openapi</span> <span class="token operator">=</span> <span class="token function"><span class="token punctuation">\\</span>OpenApi<span class="token punctuation">\\</span>scan</span><span class="token punctuation">(</span><span class="token constant">__DIR__</span><span class="token punctuation">,</span> <span class="token punctuation">[</span><span class="token string single-quoted-string">'exclude'</span> <span class="token operator">=></span> <span class="token variable">$exclude</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'pattern'</span> <span class="token operator">=></span> <span class="token variable">$pattern</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
</code></pre></div>`,31),o=[p];function c(l,i,u,r,k,d){return a(),s("div",null,o)}var f=n(e,[["render",c]]);export{h as __pageData,f as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as n,c as s,o as a,a as t}from"./app.3ef9e972.js";const h='{"title":"Using the Generator","description":"","frontmatter":{},"headers":[{"level":2,"title":"Introduction","slug":"introduction"},{"level":2,"title":"The \\\\OpenApi\\\\scan() function","slug":"the-openapi-scan-function"},{"level":2,"title":"The \\\\OpenApi\\\\Generator class","slug":"the-openapi-generator-class"}],"relativePath":"reference/generator.md"}',e={},p=t("",31),o=[p];function c(l,i,u,r,k,d){return a(),s("div",null,o)}var f=n(e,[["render",c]]);export{h as __pageData,f as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o,a as r}from"./app.3ef9e972.js";const f='{"title":"Reference","description":"","frontmatter":{},"headers":[],"relativePath":"reference/index.md"}',a={},n=r('<h1 id="reference" tabindex="-1">Reference <a class="header-anchor" href="#reference" aria-hidden="true">#</a></h1><p>In total there are a number of different aspects to using <code>swagger-php</code>. Depending on how custom your requirements are this might be limited to just annotating your code and using the command line tool.</p><p>However, <code>swagger-php</code> offers more.</p><ul><li><p><a href="./attributes.html">Attributes</a></p><p>The new way of adding meta-data to your codebase. Requires PHP 8.1</p></li><li><p><a href="./annotations.html">Docblock annotations</a></p><p>The 'traditional' way of documenting your API.</p></li><li><p>The <a href="./generator.html"><code>Generator</code></a></p><p>The <code>\\OpenAPI\\Generator</code> class is the main entry point to programmatically generate OpenAPI documents from your code.</p></li><li><p><a href="./processors.html">Processors</a></p><p><code>swagger-php</code> comes with a list of pre-defined processors that convert the raw data to a complete OpenAPI document. Custom processors can be added or existing removed to tweak swagger-php` to your requirements.</p></li></ul>',4),s=[n];function c(i,d,p,h,l,m){return o(),t("div",null,s)}var _=e(a,[["render",c]]);export{f as __pageData,_ as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o,a as r}from"./app.3ef9e972.js";const f='{"title":"Reference","description":"","frontmatter":{},"headers":[],"relativePath":"reference/index.md"}',a={},n=r("",4),s=[n];function c(i,d,p,h,l,m){return o(),t("div",null,s)}var _=e(a,[["render",c]]);export{f as __pageData,_ as default};
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as r,a}from"./app.3ef9e972.js";const u='{"title":"Processors","description":"","frontmatter":{},"headers":[{"level":2,"title":"DocBlockDescriptions","slug":"docblockdescriptions"},{"level":2,"title":"MergeIntoOpenApi","slug":"mergeintoopenapi"},{"level":2,"title":"MergeIntoComponents","slug":"mergeintocomponents"},{"level":2,"title":"ExpandClasses","slug":"expandclasses"},{"level":2,"title":"ExpandInterfaces","slug":"expandinterfaces"},{"level":2,"title":"ExpandTraits","slug":"expandtraits"},{"level":2,"title":"ExpandEnums","slug":"expandenums"},{"level":2,"title":"AugmentSchemas","slug":"augmentschemas"},{"level":2,"title":"AugmentRequestBody","slug":"augmentrequestbody"},{"level":2,"title":"AugmentProperties","slug":"augmentproperties"},{"level":2,"title":"BuildPaths","slug":"buildpaths"},{"level":2,"title":"AugmentParameters","slug":"augmentparameters"},{"level":3,"title":"Config settings","slug":"config-settings"},{"level":2,"title":"AugmentRefs","slug":"augmentrefs"},{"level":2,"title":"MergeJsonContent","slug":"mergejsoncontent"},{"level":2,"title":"MergeXmlContent","slug":"mergexmlcontent"},{"level":2,"title":"OperationId","slug":"operationid"},{"level":3,"title":"Config settings","slug":"config-settings-1"},{"level":2,"title":"CleanUnmerged","slug":"cleanunmerged"},{"level":2,"title":"CleanUnusedComponents","slug":"cleanunusedcomponents"}],"relativePath":"reference/processors.md"}',n={},s=a("",45),o=[s];function i(h,p,c,d,l,g){return r(),t("div",null,o)}var f=e(n,[["render",i]]);export{u as __pageData,f as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as r,a}from"./app.3ef9e972.js";const u='{"title":"Related projects","description":"","frontmatter":{"sidebar":false},"headers":[],"relativePath":"related-projects.md"}',n={},o=a('<h1 id="related-projects" tabindex="-1">Related projects <a class="header-anchor" href="#related-projects" aria-hidden="true">#</a></h1><table><thead><tr><th>Project</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://swagger.io/tools/swagger-ui/" target="_blank" rel="noopener noreferrer">Swagger UI</a></td><td>The webinterface for reading the generated documentation</td></tr><tr><td><a href="https://bfanger.nl/swagger-explained/" target="_blank" rel="noopener noreferrer">Swagger Explained</a></td><td>Browse the spec by using an swagger.json.</td></tr><tr><td><a href="https://github.com/DerManoMann/silex2swagger" target="_blank" rel="noopener noreferrer">silex2swagger</a></td><td>Generate swagger documentation from Silex Annotations</td></tr><tr><td><a href="https://github.com/lichunqiang/yii2-swagger" target="_blank" rel="noopener noreferrer">yii2-swagger</a></td><td>swagger-php integration with yii2</td></tr><tr><td><a href="https://github.com/DarkaOnLine/SwaggerLume" target="_blank" rel="noopener noreferrer">Lumen swagger</a></td><td>swagger-php integration with lumen/laravel</td></tr><tr><td><a href="https://github.com/nelmio/NelmioApiDocBundle" target="_blank" rel="noopener noreferrer">NelmioApiDocBundle</a></td><td>Symfony bundle on top of swagger-php</td></tr><tr><td><a href="https://github.com/kevupton/auto-swagger-ui" target="_blank" rel="noopener noreferrer">auto-swagger-ui</a></td><td>Automatically add swagger ui and json to your application</td></tr><tr><td><a href="https://github.com/DerManoMann/openapi-router" target="_blank" rel="noopener noreferrer">openapi-router</a></td><td>Configure framework routes from OpenApi annotations</td></tr><tr><td><a href="https://github.com/DerManoMann/openapi-verifier" target="_blank" rel="noopener noreferrer">openapi-verifier</a></td><td>Verify response against OpenAPI specification in PHPUnit</td></tr><tr><td><a href="https://github.com/Mermade/openapi-filter" target="_blank" rel="noopener noreferrer">openapi-filter</a></td><td>Filter internal paths, operations, parameters, etc</td></tr><tr><td><a href="https://github.com/Tobion/OpenAPI-Symfony-Routing" target="_blank" rel="noopener noreferrer">OpenAPI-Symfony-Routing</a></td><td>Load routes in Symfony based on OpenAPI annotations</td></tr><tr><td><a href="https://kizu514.com/swagit.php" target="_blank" rel="noopener noreferrer">Swag It PHP</a></td><td>Convert JSON to PHP Swagger annotations</td></tr><tr><td><a href="https://github.com/DarkaOnLine/L5-Swagger" target="_blank" rel="noopener noreferrer">Laravel Swagger</a></td><td>OpenApi or Swagger integration to Laravel</td></tr><tr><td><a href="https://github.com/DerManoMann/openapi-extras" target="_blank" rel="noopener noreferrer">openapi-extras</a></td><td>Extra annotations for swagger-php</td></tr><tr><td><a href="https://github.com/MattyRad/openapi-serialize" target="_blank" rel="noopener noreferrer">openapi-serialize</a></td><td>Serialize an object using swagger-php</td></tr></tbody></table><p>Is a related project missing? Create a pull request!</p>',3),i=[o];function d(p,s,g,l,h,f){return r(),t("div",null,i)}var _=e(n,[["render",d]]);export{u as __pageData,_ as default};
|
||||
|
|
@ -0,0 +1 @@
|
|||
import{_ as e,c as t,o as r,a}from"./app.3ef9e972.js";const u='{"title":"Related projects","description":"","frontmatter":{"sidebar":false},"headers":[],"relativePath":"related-projects.md"}',n={},o=a("",3),i=[o];function d(p,s,g,l,h,f){return r(),t("div",null,i)}var _=e(n,[["render",d]]);export{u as __pageData,_ as default};
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1 @@
|
|||
{"guide_annotations.md":"a025bdfa","guide_attributes.md":"c7f63b8c","guide_common-techniques.md":"2544a58b","guide_cookbook.md":"8e5589d6","guide_faq.md":"033d4d47","guide_generating-openapi-documents.md":"61794dae","guide_index.md":"297ab52e","guide_installation.md":"4c780c67","guide_migrating-to-v3.md":"e89d92ed","guide_migrating-to-v4.md":"5a52550a","guide_required-elements.md":"a1c3f02c","guide_under-the-hood.md":"cf05e9f4","index.md":"9d6332c2","reference_annotations.md":"5c5564ca","reference_attributes.md":"1789c26a","reference_generator.md":"c9e34f11","reference_index.md":"7a090ef2","reference_processors.md":"e2fefc48","related-projects.md":"de118782"}
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue