.docs

Contributte OpenApi

Pure PHP OpenAPI implementation for Nette Framework, supporting 3.0 and 3.1.

Content

• Setup
• Supported versions
• OpenAPI
• Version validation
• Tracy

Setup

Install package

composer require contributte/openapi

OpenAPI

• Callback.php
• Components.php
• Contact.php
• Example.php
• ExternalDocumentation.php
• Header.php
• Info.php
• License.php
• Link.php
• MediaType.php
• OAuthFlow.php
• OpenApi.php
• Operation.php
• Parameter.php
• PathItem.php
• Paths.php
• Reference.php
• RequestBody.php
• Response.php
• Responses.php
• Schema.php
• SecurityRequirement.php
• SecurityScheme.php
• Server.php
• ServerVariable.php
• Tag.php

Supported versions

OpenAPI	Support
3.0	yes
3.1	yes

tests/Cases/VersionSupportTest.php backs both rows with a complete document per version - tests/Cases/Schema/examples/complete-3-0.yaml and complete-3-1.yaml - each using every field its version defines, except where the specification makes two fields mutually exclusive and only one of them can appear. For each document the test requires that a fromArray()/toArray() round trip loses nothing and that VersionValidator reports no problem. For the fields a version introduced, it additionally requires the document to exercise them, so a later version cannot be called supported while its additions go untested.

Version validation

The schema classes accept any document, whatever version it declares. VersionValidator reports constructs that do not belong to that version - for example a 3.0 document using webhooks, which was introduced in 3.1.

use Contributte\OpenApi\Schema\OpenApi;
use Contributte\OpenApi\Validator\VersionValidator;

$openApi = OpenApi::fromArray($data);

foreach ((new VersionValidator())->validate($openApi) as $problem) {
	echo $problem; // [warning] webhooks: Attribute "webhooks" was introduced in OpenAPI 3.1, but the document declares 3.0.
}

Problems are returned, never thrown. Each one carries a level (Problem::LEVEL_WARNING or Problem::LEVEL_ERROR), a dot-separated path and a message.

A document that declares no version is read as Version::DEFAULT, which is 3.0 - the version this library implemented before it could tell versions apart.

Version compares version strings on their own:

use Contributte\OpenApi\Version;

Version::match('3.0.4', '3.0.x'); // true
Version::isSupported('3.1.1');    // true

Tracy

services:
    swaggerPanel:
        class: Contributte\OpenApi\Tracy\SwaggerPanel()
        setup:
            - setSpec([...openapi])
            - setLazySpec([@openapi, getSpec])
            - setUrl('https://petstore.swagger.io/v2/swagger.json')
            - setExpansion()
            - setFilter("role=User")
            - setTitle(MyAPI)

tracy:
	bar:
		- @swaggerPanel