{"id":13828268,"url":"https://github.com/goldspecdigital/oooas","last_synced_at":"2025-04-12T22:21:43.109Z","repository":{"id":41322434,"uuid":"150484399","full_name":"goldspecdigital/oooas","owner":"goldspecdigital","description":"An object oriented approach to generating OpenAPI specs, implemented in PHP.","archived":false,"fork":false,"pushed_at":"2022-08-09T14:03:19.000Z","size":237,"stargazers_count":229,"open_issues_count":16,"forks_count":22,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-04T01:24:28.339Z","etag":null,"topics":["oas","open-source","openapi","swagger"],"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/goldspecdigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-26T20:11:56.000Z","updated_at":"2025-03-30T12:41:33.000Z","dependencies_parsed_at":"2022-09-21T19:31:28.375Z","dependency_job_id":null,"html_url":"https://github.com/goldspecdigital/oooas","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldspecdigital%2Foooas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldspecdigital%2Foooas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldspecdigital%2Foooas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldspecdigital%2Foooas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goldspecdigital","download_url":"https://codeload.github.com/goldspecdigital/oooas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248638602,"owners_count":21137688,"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":["oas","open-source","openapi","swagger"],"created_at":"2024-08-04T09:02:39.176Z","updated_at":"2025-04-12T22:21:43.084Z","avatar_url":"https://github.com/goldspecdigital.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/goldspecdigital/oooas\"\u003e\u003cimg \n        alt=\"Object Oriented OpenAPI Specification\"\n        src=\"https://svgshare.com/i/D70.svg\" width=\"400px\"\n    \u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/goldspecdigital/oooas\"\u003e\u003cimg \n        alt=\"GitHub stars\" \n        src=\"https://img.shields.io/github/stars/goldspecdigital/oooas.svg?style=social\"\n    \u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/goldspecdigital/oooas/tags\"\u003e\u003cimg \n        alt=\"GitHub tag (latest SemVer)\" \n        src=\"https://img.shields.io/github/tag/goldspecdigital/oooas.svg\"\n    \u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/goldspecdigital/oooas/actions\"\u003e\u003cimg \n        alt=\"Build status\"\n        src=\"https://github.com/goldspecdigital/oooas/workflows/Tests/badge.svg\" \n    \u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/goldspecdigital/oooas\"\u003e\u003cimg \n        alt=\"Packagist\" \n        src=\"https://img.shields.io/packagist/dt/goldspecdigital/oooas.svg\"\n    \u003e\u003c/a\u003e\n    \u003cimg \n        alt=\"PHP from Packagist\" \n        src=\"https://img.shields.io/packagist/php-v/goldspecdigital/oooas.svg\"\n    \u003e\n    \u003cimg \n        alt=\"Dependency count\"\n        src=\"https://img.shields.io/badge/dependencies-0-brightgreen.svg\" \n    \u003e\n    \u003cimg \n        alt=\"Packagist\" \n        src=\"https://img.shields.io/packagist/l/goldspecdigital/oooas.svg\"\n    \u003e\n\u003c/p\u003e\n\n## Introduction\n\nAn object oriented approach to generating OpenAPI specs, implemented in PHP. \n\nYou can build up your API spec using immutable PHP classes, and then export the \nspec to JSON (or YAML with the help of another package).\n\nThis package is **dependency free** and makes heavy use of **PHP 7 features**, \nmainly being **type hints** and enabling **strict types**. This should make your \nlife a lot easier when working with a good IDE that can use this information.\n\n## Installing\n\nYou can install the package via composer:\n```bash\ncomposer require goldspecdigital/oooas\n```\n\n## Example\n\nSee the code sample below for the most basic usage:\n\n```php\nuse GoldSpecDigital\\ObjectOrientedOAS\\Objects\\{\n    Info, MediaType, Operation, PathItem, Response, Schema, Tag\n};\nuse GoldSpecDigital\\ObjectOrientedOAS\\OpenApi;\n\n// Create a tag for all the user endpoints.\n$usersTag = Tag::create()\n    -\u003ename('Users')\n    -\u003edescription('All user related endpoints');\n\n// Create the info section.\n$info = Info::create()\n    -\u003etitle('API Specification')\n    -\u003eversion('v1')\n    -\u003edescription('For using the Example App API');\n    \n// Create the user schema.\n$userSchema = Schema::object()\n    -\u003eproperties(\n        Schema::string('id')-\u003eformat(Schema::FORMAT_UUID),\n        Schema::string('name'),\n        Schema::integer('age')-\u003eexample(23),\n        Schema::string('created_at')-\u003eformat(Schema::FORMAT_DATE_TIME)\n    );\n    \n// Create the user response.\n$userResponse = Response::create()\n    -\u003estatusCode(200)\n    -\u003edescription('OK')\n    -\u003econtent(\n        MediaType::json()-\u003eschema($userSchema)\n    );\n    \n// Create the operation for the route (i.e. GET, POST, etc.).\n$showUser = Operation::get()\n    -\u003eresponses($userResponse)\n    -\u003etags($usersTag)\n    -\u003esummary('Get an individual user')\n    -\u003eoperationId('users.show');\n    \n// Define the /users path along with the supported operations.\n$usersPath = PathItem::create()\n    -\u003eroute('/users')\n    -\u003eoperations($showUser);\n    \n// Create the main OpenAPI object composed off everything created above.\n$openApi = OpenApi::create()\n    -\u003eopenapi(OpenApi::OPENAPI_3_0_2)\n    -\u003einfo($info)\n    -\u003epaths($usersPath)\n    -\u003etags($usersTag);\n    \nheader('Content-Type: application/json');\necho $openApi-\u003etoJson();\n```\n\n### YAML output\n\nUsing the same code above will output the following YAML:\n\n\u003e In this example, the YAML may seem simpler to look at, however once the spec\nstarts to increase in size - the ability to reuse objects and split them into\nseparate files easily will be a massive help.\n\n```yaml\nopenapi: 3.0.2\ninfo:\n  title: API Specification\n  description: For using the Example App API\n  version: v1\npaths:\n  \"/users\":\n    get:\n      tags:\n      - Users\n      summary: Get an individual user\n      operationId: users.show\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id:\n                    format: uuid\n                    type: string\n                  name:\n                    type: string\n                  age:\n                    type: integer\n                    example: 23\n                  created_at:\n                    format: date-time\n                    type: string\ntags:\n- name: Users\n  description: All user related endpoints\n```\n\n### Outputting as JSON or YAML\n\nBuilt in output to YAML has been omitted on purpose to keep this package\ndependency free. However, you can easily convert the array to a YAML string \nusing several open source packages. See below for an example of  outputting to \nboth JSON and YAML:\n\n```php\nuse GoldSpecDigital\\ObjectOrientedOAS\\OpenApi;\nuse Symfony\\Component\\Yaml\\Yaml;\n\n$openApi = OpenApi::create();\n\n$json = $openApi-\u003etoJson();\n$array = $openApi-\u003etoArray();\n$yaml = Yaml::dump($array);\n```\n\n## Guidance\n\nIf you want to learn more about the OpenAPI schema, then have a look at the \nofficial [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md).\n\nAlternatively, if you would like a quick reference, then check out the \n[OpenAPI Map](https://openapi-map.apihandyman.io/?version=3.0) project created \nby [Arnaud Lauret](http://apihandyman.io/).\n\nYou can use this interactive tool to figure out what objects go where and how\nthey relate to one another.\n\n## Usage\n\n### Setting and unsetting properties\n\nEach object has setter methods for it's supported properties. Most of these \nmethods allow `null` values which will need to be explicitly passed (see the \nnext example for how to unset using variadic setter methods). This will have the \neffect of unsetting the property:\n\n```php\n$info = Info::create()\n    -\u003etitle('Example API');\n\n$openApi = OpenApi::create()\n    -\u003einfo($info);\necho $openApi-\u003etoJson(); // '{\"info\": {\"title\": \"Example API\"}}'\n\n$openApi = $openApi-\u003einfo(null);\necho $openApi-\u003etoJson(); // '{}'\n```\n\nFor variadic setter methods, if you call the method and don't supply any\nparameters, then this will have the effect of unsetting the property:\n\n```php\n$path = PathItem::create()\n    -\u003eroute('/users');\n\n$openApi = OpenApi::create()\n    -\u003epaths($path);\necho $openApi-\u003etoJson(); // '{\"paths\": {\"/users\": []}}'\n\n$openApi = $openApi-\u003epaths();\necho $openApi-\u003etoJson(); // '{}'\n```\n\n### Retrieving properties\n\nYou can easily retrieve a property using a magic getter. These have been\nimplemented for all properties for every object. DocBlocks have been provided\nto give better auto-completion in IDEs:\n\n```php\n$info = Info::create()-\u003etitle('Example API');\n\necho $info-\u003etitle; // 'Example API'\n```\n\n### Object ID\n\nEvery object has an optional `$objectId` property which is a `string` and can \neither be set in the class constructor or the preferred `create()` method. This \nproperty is used when a parent object needs to use a name for the children.\n\nAn example of this in use is when a schema object is composed of other schema\nproperties:\n\n```php\n$schema = Schema::create()\n    -\u003etype(Schema::TYPE_OBJECT)\n    -\u003eproperties(\n        Schema::create('username')-\u003etype(Schema::TYPE_STRING),\n        Schema::create('age')-\u003etype(Schema::TYPE_INTEGER)\n    );\n    \necho $schema-\u003etoJson();\n/* \n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"username\": {\n      \"type\": \"string\"\n    },\n    \"age\": {\n      \"type\": \"integer\"\n    }\n  }\n} \n*/\n``` \n\nIf an object contains any helper creation methods, then these methods also allow\nyou to specify the `$objectId` property as a parameter. The code sample below is\nfunctionally identical to the one above:\n\n```php\n$schema = Schema::object()\n    -\u003eproperties(\n        Schema::string('username'),\n        Schema::integer('age')\n    );\n    \necho $schema-\u003etoJson();\n/* \n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"username\": {\n      \"type\": \"string\"\n    },\n    \"age\": {\n      \"type\": \"integer\"\n    }\n  }\n} \n*/\n``` \n\n### $ref\n\nThe use of `$ref` has been applied to every single object to use as you wish.\nYou may substitute any object for a `$ref` by invoking the `ref()` static method \non the object class: \n\n```php\n$schema = AllOf::create()\n    -\u003eschemas(\n        Schema::ref('#/components/schemas/ExampleSchema')\n    );\n    \necho $schema-\u003etoJson();\n/*\n{\n  \"allOf\": [\n    [\"$ref\": \"#/components/schemas/ExampleSchema\"]\n  ]\n}\n*/\n```\n\n### Specification extensions\n\nYou can add [specification extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specificationExtensions)\nto all objects:\n\n```php\n$schema = Schema::create()\n    -\u003ex('foo', 'bar')\n    -\u003ex('items', Schema::array()-\u003eitems(Schema::string()));\n    \necho $schema-\u003etoJson();\n/*\n{\n  \"x-foo\": \"bar\",\n  \"x-items\": {\n    \"type\": \"array\",\n    \"items\": {\n      \"type\": \"string\"\n    }\n  }\n}\n*/\n\necho $schema-\u003e{'x-foo'}; // 'bar'\n```\n\nYou can also unset specification extensions by invoking the `x()` method and\nonly providing the key:\n\n```php\n$schema = Schema::create()\n    -\u003ex('foo', 'bar')\n    -\u003ex('items', Schema::array()-\u003eitems(Schema::string()));\n\n$schema = $schema-\u003ex('foo');\n    \necho $schema-\u003etoJson();\n/*\n{\n  \"x-items\": {\n    \"type\": \"array\",\n    \"items\": {\n      \"type\": \"string\"\n    }\n  }\n}\n*/\n```\n\nTo retrieve an array of all the specification extensions you can call the `$x`\nproperty:\n\n```php\n$schema = Schema::create()\n    -\u003ex('foo', 'bar')\n    -\u003ex('items', Schema::array()-\u003eitems(Schema::string()));\n\necho json_encode($schema-\u003ex);\n/*\n{\n  \"x-foo\": \"bar\",\n  \"x-items\": {\n    \"type\": \"array\",\n    \"items\": {\n      \"type\": \"string\"\n    }\n  }\n}\n*/\n```\n\n### Validation\n\nIn order to perform schema validation you must first install the\n`justinrainbow/json-schema` package:\n\n```bash\ncomposer require justinrainbow/json-schema:^5.2\n```\n\nOnce installed, you may now make use of the `validate()` method on the `OpenApi`\nobject:\n\n```php\n$openApi = OpenApi::create();\n$openApi-\u003evalidate();\n```\n\n_If you haven't installed the `justinrainbow/json-schema` package and attempt to \nuse the `validate()` method, then a `RuntimeException` will be thrown._\n\nIf validation fails for the schema, then a \n`GoldSpecDigital\\ObjectOrientedOAS\\Exceptions\\ValidationException` will be \nthrown. You can use the `getErrors()` method on this exception to retrieve all\nof the validation errors.\n\n## Running the tests\n\nTo run the test suite you can use the following commands:\n\n```bash\n# To run both style and unit tests.\ncomposer test\n\n# To run only style tests.\ncomposer test:style\n\n# To run only unit tests.\ncomposer test:unit\n```\n\nIf you receive any errors from the style tests, you can automatically fix most,\nif not all of the issues with the following command:\n\n```bash\ncomposer fix:style\n```\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of \nconduct, and the process for submitting pull requests to us.\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, \nsee the [tags on this repository](https://github.com/goldspecdigital/oooas/tags). \n\n## Authors\n\n* [GoldSpec Digital](https://github.com/goldspecdigital)\n\nSee also the list of [contributors](https://github.com/goldspecdigital/oooas/contributors) \nwho participated in this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) \nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldspecdigital%2Foooas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoldspecdigital%2Foooas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldspecdigital%2Foooas/lists"}