{"id":22151028,"url":"https://github.com/justcoded/swagger-tools","last_synced_at":"2026-02-27T13:36:06.173Z","repository":{"id":54534828,"uuid":"132496944","full_name":"justcoded/swagger-tools","owner":"justcoded","description":"Swagger docs generation tools","archived":false,"fork":false,"pushed_at":"2025-01-28T12:24:57.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-11-13T00:09:22.356Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justcoded.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2018-05-07T17:53:46.000Z","updated_at":"2025-01-28T12:21:25.000Z","dependencies_parsed_at":"2024-10-16T16:09:30.460Z","dependency_job_id":"4cc0ecb9-5b2e-4a5c-84a8-34b269808e4a","html_url":"https://github.com/justcoded/swagger-tools","commit_stats":{"total_commits":18,"total_committers":3,"mean_commits":6.0,"dds":"0.11111111111111116","last_synced_commit":"06376b0cc48e44701ef3c33f1175224ebfa4837a"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/justcoded/swagger-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fswagger-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fswagger-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fswagger-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fswagger-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justcoded","download_url":"https://codeload.github.com/justcoded/swagger-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justcoded%2Fswagger-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29897460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T12:09:13.686Z","status":"ssl_error","status_checked_at":"2026-02-27T12:09:13.282Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-12-02T00:29:49.102Z","updated_at":"2026-02-27T13:36:06.148Z","avatar_url":"https://github.com/justcoded.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger Tools\n\nThis repository contains an examples of OAS/Swagger API documentations with several tools and a guide to create \ngood API documentation and use it to build a Mock server.\n\n## Why to use API documentation?\n\nWhen two different teams develop backend and frontend separately - they both need a document stated the request\nand response data format. Of course, they make a deal in Slack for example and try to remember it. \nHowever, in this way your product become a \"black box\", which is highly difficult to support.\n\nAs a solution we propose to create a structured API documentation, which is not dependent on some specific technology. \nI mean that you don't need to learn some PHP or JavaScript to create such documentation.\nNowadays, there are two popular formats: [OAS](https://swagger.io/specification/) (Open API Specification) and \n[RAML](https://raml.org/) (RESTful API Modeling Language). RAML is pretty cool, but OAS has bigger community and OAS \nbecame our choice. And unfortunately, we need to use outdated OAS2 format (aka \"Swagger\"), because OAS3 is \nnot supported by numerous tools you will probably need it future.\n\n## Contents\n\nYou can find in this repo:\n\n* Examples of swagger API documentation in OAS2, OAS3 in Yaml format. _It's a multi-document structure with cross-docs references, \nto keep things DRY (Don't Repeat Yourself)_\n* [Swagger UI](https://swagger.io/tools/swagger-ui/) viewer for API documentation\n* PHP tool to **merge multi-document yaml** to a single document. _Unfortunately available tools works only with single documents._\n* PHP tool to **generate fake object examples** with [Faker](https://github.com/fzaninotto/Faker) library.\n\n## Writing Docs\n\n### Setup project\n\nTo start with - you can clone this repository to some webserver. It uses static html and javascript, so you don't need any\nspecial server configuration. You will need composer package manager on the server.\n\n```bash\ngit clone https://github.com/justcoded/swagger-tools.git /path/to/docroot/swagger\ncd /path/to/docroot/swagger\ncomposer install\n```\n\nThat's it, you can open `http://mydomain.com/swagger/` in browser and you will get a Swagger UI with our sample doc.\n\n_Or you can try to check swagger UI running nginx with docker like this:_\n```bash\ndocker run -p 8080:80 --name swagger-tools -v ./:/usr/share/nginx/html:ro nginx\n```\n\n### Create your docs\n\nNow let's go to the `examples` folder. You can copy some folder to start with. \nAfter that you will need to update `index.html` to point to your new docs by default:\n\n```js\n\u003cscript\u003e\nwindow.onload = function() {\n\n  // Build a system\n  const ui = SwaggerUIBundle({\n\turl: \"./examples/jsonapi/swagger.yaml\",\n\t...\n\n``` \n\nAs already mentioned we use OAS2 format, specification can be found here:\n\n* https://swagger.io/docs/specification/2-0/basic-structure/\n* https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md\n\nIf you are new to the swagger format you will need to learn such declarations:\n\n- Definitions Object (for Models and Objects)\n- Path Object - for routes\n- Parameter Object - for defining parameters\n- Response Object - for response\n\nDocs structure we propose to use:\n\n```\n- routes/\t\t\t# Routes/Paths definitions grouped by section\n\t- auth.yaml\n\t- users.yaml\n\n- models.yaml\t\t\t# Models/Requests definition\n- params.yaml\t\t\t# Params, which are similar for paths in different routes groups\n- responses.yaml \t\t# General responses definitions like 204, 401, 403, 404, 422, 500, etc.\n- swagger.yaml \t\t\t# Main file, which includes other files\n```\n\nBecause of limitations of OAS2 format we need to list ALL routes inside main file:\n\n```yaml\npaths:\n  /auth/sign-in:\n    $ref: \"routes/auth.yaml#/paths/login\"\n  /auth/verify:\n    $ref: \"routes/auth.yaml#/paths/verify\"\n  /auth/password-reset:\n    $ref: \"routes/auth.yaml#/paths/resetPassword\"\n  ...\n```\n\nHaving the examples I think all other things are self-explanatory.\n\n### Swagger Editor\n\nWe recommend to use WebStorm or PHPStorm (or any other Jetbrains IDE) to edit swagger yaml files. To have autocompletions \non swagger identifiers and references you will need to install plugin called [Swagger Plugin](https://plugins.jetbrains.com/plugin/8347-swagger-plugin).\n\n### JSON format\n\nWhen you develop an API it's always a hard decision on what format JSON should be looks like. To solve this problem we \nsuggest to follow JSONAPI specs: [http://jsonapi.org/](http://jsonapi.org/)\n\nIn general, it defines that we need to transfer data in a format like this:\n\n```js\n{\n\t\"data\": [{ // collection or resource itself\n\t\t\"type\": 'resource type',\n\t\t\"id\": 'some id',\n\t\t\"attributes\": {\n\t\t\t// resource attribute\n\t\t},\n\t\t\"relationships\": {\n\t\t\t'relation name': {\n\t\t\t\t\"data\": { \"type\": \"resource type\", \"id\": \"some id\" }\n\t\t\t}\n\t\t\t// ...\n\t\t}\n\t}],\n\t\"included\": [{ // data for related resources\n        \"type\": \"related resource type\",\n        \"id\": \"some id\",\n        \"attributes\": {\n        \t// related resource data\n        }\n        // ...\n    }],\n\t\"meta\": {\n\t\t// some other data like pagination info, tokens, etc.\n\t}\n}\n```\n\nThis format is good for JavaScript libraries such as React.js, Vue.js and Angular, because it's super easy to populate scope \nbased on resource types. \n\nJSONAPI has a lot of ready-to-use implementations: http://jsonapi.org/implementations/\n\n#### JSONAPI Format For Non-resource Requests\n\nUnfortunately, this specification doesn't answer how to form non-resource requests. Usually these are some actions, for example \"search\".\n\nWe suggest to define that we can transfer a document-type model of type \"userInput\", which can vary from route to route.\nLooks like this:\n\n```js\n{\n\t\"data\": {\n\t\t\"type\": \"userInput\",\n\t\t\"attributes\": {\n\t\t\t// key/value pairs of user input data\n\t\t}\n\t}\n}\n```  \n\n## PHP Tools\n\n* Merge multi-document swagger YAML documentation\n* Generate fake data to enums for mock servers\n\n### Merge tool\n\n\t./cli/swagger-merge.php examples/v2.0/swagger.yaml \u003e merged-swagger2.yaml\n\n### Faker tool\n\nAdd to your properties x-faker attribute:\n\n\tswagger: '2.0'\n    definitions:\n      User:\n        type: object\n        properties:\n          id:\n            type: integer\n            format: int64\n            minimum: 1\n          email:\n            type: string\n            format: email\n            x-faker: email\n          first_name:\n            type: string\n            x-faker: firstName\n          last_name:\n            type: string\n            x-faker: lastName\n            \nRun command:\n\n\t./cli/swagger-faker.php examples/merged/swagger2.yaml -n10 -r -c \u003e swagger-faked.yaml\n\nYou will get:\n\n\tdefinitions:\n      User:\n        type: object\n        properties:\n          id:\n            type: integer\n            format: int64\n            minimum: 1\n          email:\n            type: string\n            format: email\n            x-faker: email\n            enum:\n              - muhammad.schuster@yahoo.com\n              - hansen.rudy@nolan.com\n              - nlittel@hotmail.com\n              - gleason.araceli@witting.com\n              - sreichert@hotmail.com\n              - swift.dayna@kris.com\n              - russel55@gmail.com\n              - dicki.emery@hotmail.com\n              - morris77@hotmail.com\n              - lprice@yahoo.com\n          first_name:\n            type: string\n            x-faker: firstName\n            enum:\n              - Denis\n              - Donna\n              - Elissa\n              - Brandyn\n              - Dino\n              - Linda\n              - Sadye\n              - Kenneth\n              - Michel\n              - Theo\n\n\t\t  ...\n\n\t    required:\n\t  \t- id\n\t  \t- email\n\t  \t- first_name\n\t  \t- last_name\n\t  \t- profile\n\n# Using this repo as dependency\n\nOf course, you can add this repository as dependency to your project, symlink swagger ui assets to your public repository\nand create your template inside your framework to print swagger ui interface, pointing to some generated doc.\n\nAs an example we created Yii extension, wrapping our PHP tools: https://github.com/justcoded/yii2-swaggerviewer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustcoded%2Fswagger-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustcoded%2Fswagger-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustcoded%2Fswagger-tools/lists"}