{"id":13579255,"url":"https://github.com/cebe/php-openapi","last_synced_at":"2025-05-14T01:07:05.853Z","repository":{"id":39005545,"uuid":"154310978","full_name":"cebe/php-openapi","owner":"cebe","description":"Read and write OpenAPI yaml/json files and make the content accessible in PHP objects.","archived":false,"fork":false,"pushed_at":"2024-08-09T15:09:43.000Z","size":688,"stargazers_count":472,"open_issues_count":59,"forks_count":91,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-10-29T23:50:01.483Z","etag":null,"topics":["api","api-spec","hacktoberfest","openapi","openapi3","php","schema"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cebe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-23T10:46:11.000Z","updated_at":"2024-10-25T06:24:36.000Z","dependencies_parsed_at":"2024-01-16T20:30:04.088Z","dependency_job_id":"68db712b-f9f4-4f15-a873-ae2f89b4b4f3","html_url":"https://github.com/cebe/php-openapi","commit_stats":{"total_commits":250,"total_committers":27,"mean_commits":9.25925925925926,"dds":0.272,"last_synced_commit":"020d72b8e3a9a60bc229953e93eda25c49f46f45"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cebe%2Fphp-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cebe%2Fphp-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cebe%2Fphp-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cebe%2Fphp-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cebe","download_url":"https://codeload.github.com/cebe/php-openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248353179,"owners_count":21089577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-spec","hacktoberfest","openapi","openapi3","php","schema"],"created_at":"2024-08-01T15:01:37.776Z","updated_at":"2025-04-11T06:25:21.283Z","avatar_url":"https://github.com/cebe.png","language":"PHP","readme":"# php-openapi\n\nRead and write [OpenAPI](https://www.openapis.org/) 3.0.x YAML and JSON files and make the content accessible in PHP objects.\n\nIt also provides a CLI tool for validating and converting OpenAPI 3.0.x Description files.\n\n[![Latest Stable Version](https://poser.pugx.org/cebe/php-openapi/v/stable)](https://packagist.org/packages/cebe/php-openapi)\n[![Total Downloads](https://poser.pugx.org/cebe/php-openapi/downloads)](https://packagist.org/packages/cebe/php-openapi)\n[![Build Status](https://github.com/cebe/php-openapi/workflows/CI/badge.svg)](https://github.com/cebe/php-openapi/actions)\n\n\n## Install\n\n    composer require cebe/php-openapi\n\n## Requirements\n\n- PHP 7.1 or higher (works fine with PHP 8)\n\n## Used by\n\nThis library provides a low level API for reading and writing OpenAPI files. It is used by higher level tools to\ndo awesome work:\n\n- [cebe/yii2-openapi](https://github.com/cebe/yii2-openapi) Code Generator for REST API from OpenAPI 3 Descriptions, includes fake data generator.\n- [cebe/yii2-app-api](https://github.com/cebe/yii2-app-api) Yii framework application template for developing API-first applications.\n- [league/openapi-psr7-validator](https://github.com/thephpleague/openapi-psr7-validator) validates PSR-7 messages (HTTP request/response) against OpenAPI descriptions.\n- [dsuurlant/response2schema](https://github.com/dsuurlant/response2schema) a quick and easy tool for generating OpenAPI schemas based on example data.\n- [hotmeteor/spectator](https://github.com/hotmeteor/spectator) a light-weight OpenAPI testing tool for existing Laravel test suite.\n- [googoogajoob/openapi-slim4](https://github.com/googoogajoob/openapi-slim4) Configure the paths of a slim4 application from an openapi definition.\n- ... ([add yours](https://github.com/cebe/php-openapi/edit/master/README.md#L24))\n\n## Usage\n\n### CLI Tool\n\n    $ vendor/bin/php-openapi help\n    PHP OpenAPI 3 tool\n    ------------------\n    by Carsten Brandt \u003cmail@cebe.cc\u003e\n\n    Usage:\n      php-openapi \u003ccommand\u003e [\u003coptions\u003e] [input.yml|input.json] [output.yml|output.json]\n\n      The following commands are available:\n\n        validate   Validate the API Description in the specified input file against the OpenAPI v3.0 schema.\n                   Note: the validation is performed in two steps. The results are composed of\n                    (1) structural errors found while reading the API Description file, and\n                    (2) violations of the OpenAPI v3.0 schema.\n\n                   If no input file is specified input will be read from STDIN.\n                   The tool will try to auto-detect the content type of the input, but may fail\n                   to do so. You may specify --read-yaml or --read-json to force the file type.\n\n                   Exits with code 2 on validation errors, 1 on other errors and 0 on success.\n\n        convert    Convert a JSON or YAML input file to JSON or YAML output file.\n\n                   If no input file is specified input will be read from STDIN.\n                   If no output file is specified output will be written to STDOUT.\n                   The tool will try to auto-detect the content type of the input and output file, but may fail\n                   to do so. You may specify --read-yaml or --read-json to force the input file type.\n                   and --write-yaml or --write-json to force the output file type.\n\n                   By default all references are resolved (replaced with the object referred to). You can control\n                   handling of references with the following arguments:\n\n                   --resolve-none      Do not resolve references.\n                   --resolve-external  Only resolve references that point to external files.\n                                       This process is often referred to as \"inlining\".\n                   --resolve-all       Resolve all references (default).\n                                       Recursive pointers will stay references.\n\n        inline     Convert a JSON or YAML input file to JSON or YAML output file and\n                   resolve all external references. The output will be a single API Description file.\n                   This is a shortcut for calling convert --resolve-external.\n\n        help       Shows this usage information.\n\n      Options:\n\n        --read-json   force reading input as JSON. Auto-detect if not specified.\n        --read-yaml   force reading input as YAML. Auto-detect if not specified.\n        --write-json  force writing output as JSON. Auto-detect if not specified.\n        --write-yaml  force writing output as YAML. Auto-detect if not specified.\n        -s, --silent  silent mode. Will hide all success/information messages and only print errors.\n\n\n### Reading API Description Files\n\nRead OpenAPI Description from JSON file:\n\n```php\nuse cebe\\openapi\\Reader;\n\n// realpath is needed for resolving references with relative Paths or URLs\n$openapi = Reader::readFromJsonFile(realpath('openapi.json'));\n```\n\nRead OpenAPI Description from YAML:\n\n```php\nuse cebe\\openapi\\Reader;\n\n// realpath is needed for resolving references with relative Paths or URLs\n$openapi = Reader::readFromYamlFile(realpath('openapi.yaml'));\n// you may also specify the URL to your API Description file\n$openapi = Reader::readFromYamlFile('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml');\n```\n\nAccess API Description data:\n\n```php\necho $openapi-\u003eopenapi; // openAPI version, e.g. 3.0.0\necho $openapi-\u003einfo-\u003etitle; // API title\nforeach($openapi-\u003epaths as $path =\u003e $definition) {\n    // iterate path definitions\n}\n```\n\nObject properties are exactly like in the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#openapi-specification).\nYou may also access additional properties added by [specification extensions](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#specificationExtensions).\n\nRead a component schema and its properties for below spec:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: Test API\n  version: 1.0.0\npaths:\n  /foo:\n    put:\n      description: create foo\n      responses:\n        '200':\n          description: request succeeded          \ncomponents:  \n  schemas:\n    Foo:\n      description: This is an description\n      type: object\n      properties:\n        message:\n          type: string\n        code:\n          type: number\n```\n\n```php\n# read a component schema\n$foo = $openapi-\u003ecomponents-\u003eschemas['Foo'];\n\n# read a property of schema\n$foo-\u003eproperties['message']\n```\n\n### Writing API Description Files\n\n```php\nuse cebe\\openapi\\spec\\OpenApi;\nuse cebe\\openapi\\spec\\PathItem;\n\n// create base API Description\n$openapi = new OpenApi([\n    'openapi' =\u003e '3.0.2',\n    'info' =\u003e [\n        'title' =\u003e 'Test API',\n        'version' =\u003e '1.0.0',\n    ],\n    'paths' =\u003e [],\n]);\n// manipulate description as needed\n$openapi-\u003epaths['/test'] = new PathItem([\n    'description' =\u003e 'something'\n]);\n// ...\n\n$json = \\cebe\\openapi\\Writer::writeToJson($openapi);\n```\n\nresults in the following JSON data:\n\n```json\n{\n    \"openapi\": \"3.0.0\",\n    \"info\": {\n        \"title\": \"Test API\",\n        \"version\": \"1.0.0\"\n    },\n    \"paths\": {\n        \"/test\": {\n            \"description\": \"something\"\n        }\n    }\n}\n```\n\n### Writing API Description Files using prepared Objects\n\nSince version 1.2.0, the above example can also be written like this (passing objects instead of arrays):\n\n```php\nuse cebe\\openapi\\spec\\OpenApi;\nuse cebe\\openapi\\spec\\PathItem;\nuse cebe\\openapi\\spec\\Info;\n\n\n// create base API Description\n$openapi = new OpenApi([\n    'openapi' =\u003e '3.0.2',\n    'info' =\u003e new Info([\n        'title' =\u003e 'Test API',\n        'version' =\u003e '1.0.0',\n    ]),\n    'paths' =\u003e [\n        '/test' =\u003e new PathItem([\n            'description' =\u003e 'something'\n        ]),\n    ],\n]);\n$json = \\cebe\\openapi\\Writer::writeToJson($openapi);\n```\n\n### Reading API Description Files and Resolving References\n\nIn the above we have passed the raw JSON or YAML data to the Reader. In order to be able to resolve\nreferences to structures in external files, we must provide the full context.\n\n```php\nuse cebe\\openapi\\Reader;\nuse cebe\\openapi\\spec\\OpenAPI;\nuse cebe\\openapi\\ReferenceContext;\n\n// there are two different modes for resolving references:\n// ALL: resolve all references, which will result in a large description with a lot of repetition\n// but no references (except if there are recursive references, these will stop at some level)\n$mode = ReferenceContext::RESOLVE_MODE_ALL;\n// INLINE: only references to external files are resolved, references to places in the current file\n// are still Reference objects.\n$mode = ReferenceContext::RESOLVE_MODE_INLINE;\n\n// an absolute URL or file path is needed to allow resolving external references\n$openapi = Reader::readFromJsonFile('https://www.example.com/api/openapi.json', OpenAPI::class, $mode);\n$openapi = Reader::readFromYamlFile('https://www.example.com/api/openapi.yaml', OpenAPI::class, $mode);\n```\n\nIf data has been loaded in a different way you can manually resolve references like this by giving a context:\n\n```php\n$openapi-\u003eresolveReferences(\n    new \\cebe\\openapi\\ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml')\n);\n```\n\n### Validation\n\nThe library provides simple validation operations, that check basic OpenAPI spec requirements.\nThis is the same as \"structural errors found while reading the API Description file\" from the CLI tool.\nThis validation does not include checking against the OpenAPI v3.0 JSON schema, this is only implemented in the CLI.\n\n```\n// return `true` in case no errors have been found, `false` in case of errors.\n$specValid = $openapi-\u003evalidate();\n// after validation getErrors() can be used to retrieve the list of errors found.\n$errors = $openapi-\u003egetErrors();\n```\n\n\u003e **Note:** Validation is done on a very basic level and is not complete. So a failing validation will show some errors,\n\u003e but the list of errors given may not be complete. Also a passing validation does not necessarily indicate a completely\n\u003e valid spec.\n\n\n## Completeness\n\nThis library is currently work in progress, the following list tracks completeness:\n\n- [x] read OpenAPI 3.0 JSON\n- [x] read OpenAPI 3.0 YAML\n- [ ] OpenAPI 3.0 Schema\n  - [x] OpenAPI Object\n  - [x] Info Object\n  - [x] Contact Object\n  - [x] License Object\n  - [x] Server Object\n  - [x] Server Variable Object\n  - [x] Components Object\n  - [x] Paths Object\n  - [x] Path Item Object\n  - [x] Operation Object\n  - [x] External Documentation Object\n  - [x] Parameter Object\n  - [x] Request Body Object\n  - [x] Media Type Object\n  - [x] Encoding Object\n  - [x] Responses Object\n  - [x] Response Object\n  - [x] Callback Object\n  - [x] Example Object\n  - [x] Link Object\n    - [ ] [Runtime Expressions](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#runtime-expressions)\n  - [x] Header Object\n  - [x] Tag Object\n  - [x] Reference Object\n  - [x] Schema Object\n    - [x] load/read\n    - [ ] validation\n  - [x] Discriminator Object\n  - [x] XML Object\n  - [x] Security Scheme Object\n  - [x] OAuth Flows Object\n  - [x] OAuth Flow Object\n  - [x] Security Requirement Object\n\n# Development\n\nYou may use the docker environment for local development:\n\n    docker-compose build\n    make IN_DOCKER=1 install\n    make IN_DOCKER=1 test\n    ...\n\n\n# Support\n\n**Need help with your API project?**\n\nProfessional support, consulting as well as software development services are available:\n\nhttps://www.cebe.cc/en/contact\n\nDevelopment of this library is sponsored by [cebe.:cloud: \"Your Professional Deployment Platform\"](https://cebe.cloud).\n","funding_links":[],"categories":["PHP"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcebe%2Fphp-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcebe%2Fphp-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcebe%2Fphp-openapi/lists"}