> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/vendor/zircote/swagger-php.md).

# swagger-php

[![Build Status](https://img.shields.io/github/actions/workflow/status/zircote/swagger-php/build.yml?branch=master)](https://github.com/zircote/swagger-php/actions?query=workflow:build) [![Total Downloads](https://img.shields.io/packagist/dt/zircote/swagger-php.svg)](https://packagist.org/packages/zircote/swagger-php) [![License](https://img.shields.io/badge/license-Apache2.0-blue.svg)](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/vendor/zircote/swagger-php/LICENSE/README.md)

## swagger-php

Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php) (preferred) or [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (requires additional `doctrine/annotations` library).

See the [documentation website](https://zircote.github.io/swagger-php/guide/using-attributes.html) for supported attributes and annotations.

Annotations are deprecated and may be removed in a future release of swagger-php.

### Features

* Compatible with the OpenAPI **3.0** and **3.1** specification.
* Extracts information from code and existing phpdoc annotations.
* Command-line interface available.
* [Documentation site](https://zircote.github.io/swagger-php/) with a getting started guide.
* Exceptional error reporting (with hints, context)
* As of PHP 8.1, all annotations are also available as PHP attributes

### OpenAPI version support

`swagger-php` allows to generate specs either for **OpenAPI 3.0.0** or **OpenAPI 3.1.0**. By default, the spec will be in version `3.0.0`. The command line option `--version` may be used to change this to `3.1.0`.

Programmatically, the method `Generator::setVersion()` can be used to change the version.

### Requirements

`swagger-php` requires at least PHP 7.4 for annotations and PHP 8.1 for using attributes.

### Installation (with [Composer](https://getcomposer.org))

```shell
composer require zircote/swagger-php
```

For cli usage from anywhere, install swagger-php globally and make sure to place the `~/.composer/vendor/bin` directory in your PATH so the `openapi` executable can be located by your system.

```shell
composer global require zircote/swagger-php
```

#### radebatz/type-info-extras

`swagger-php` version `5.5` introduces a new type resolver used internally to determine the schema type of properties (and other elements with a schema).

By default, a custom `LegacyTypeResolver` is used. If you are on PHP 8.2 or higher, the `TypeInfoTypeResolver` can be used instead. For this the [radebatz/type-info-extras](https://github.com/DerManoMann/type-info-extras) package is required. Since it is optional, it needs to be installed manually. It will also add `symfony/type-info` as a dependency:

```shell
composer require radebatz/type-info-extras
```

If the library code is detected, `swagger-php` will automatically use it. Advantages are re-use of 3rd party code, better stability and compatibility with future PHP versions.

#### doctrine/annotations

As of version `4.8` the [doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) library **is optional** and **no longer installed by default**.

If your code uses doctrine annotations you will need to install that library manually:

```shell
composer require doctrine/annotations
```

### Usage

Add annotations to your php files.

```php
/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */
```

Visit the [Documentation website](https://zircote.github.io/swagger-php/) for the [Getting started guide](https://zircote.github.io/swagger-php/guide) or look at the [examples directory](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/vendor/zircote/swagger-php/docs/examples/README.md) for more examples.

#### Usage from php

Generate always-up-to-date documentation.

```php
<?php
require("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();
```

Documentation of how to use the `Generator` class can be found in the [Generator reference](https://zircote.github.io/swagger-php/reference/generator).

#### Usage from the Command Line Interface

The `openapi` command line interface can be used to generate the documentation to a static yaml/json file.

```shell
./vendor/bin/openapi --help
```

#### Usage from the Deserializer

Generate the OpenApi annotation object from a json string, which makes it easier to manipulate objects programmatically.

```php
<?php

use OpenApi\Serializer;

$serializer = new Serializer();
$openapi = $serializer->deserialize($jsonString, 'OpenApi\Annotations\OpenApi');
echo $openapi->toJson();
```

### [Contributing](/senselab-docs/vendor/zircote/swagger-php/contributing.md)

### More on OpenApi & Swagger

* <https://swagger.io>
* <https://www.openapis.org>
* [OpenApi Documentation](https://swagger.io/docs/)
* [OpenApi Specification](http://swagger.io/specification/)
* [Related projects](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/vendor/zircote/swagger-php/docs/related-projects.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/vendor/zircote/swagger-php.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.