PHPackages justcoded/swagger-tools - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. justcoded/swagger-tools ActiveProject[API Development](/categories/api) justcoded/swagger-tools ======================= Scripts to work with Swagger documentations v3.1.0(1y ago)025.4k↓32.1%1BSD-3-ClausePHPPHP >=8.0.0 Since Jul 18Pushed 1y ago3 watchersCompare [ Source](https://github.com/justcoded/swagger-tools)[ Packagist](https://packagist.org/packages/justcoded/swagger-tools)[ RSS](/packages/justcoded-swagger-tools/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (6)Dependencies (3)Versions (8)Used By (0) Swagger Tools ============= [](#swagger-tools) This repository contains an examples of OAS/Swagger API documentations with several tools and a guide to create good API documentation and use it to build a Mock server. Why to use API documentation? ----------------------------- [](#why-to-use-api-documentation) When two different teams develop backend and frontend separately - they both need a document stated the request and response data format. Of course, they make a deal in Slack for example and try to remember it. However, in this way your product become a "black box", which is highly difficult to support. As a solution we propose to create a structured API documentation, which is not dependent on some specific technology. I mean that you don't need to learn some PHP or JavaScript to create such documentation. Nowadays, there are two popular formats: [OAS](https://swagger.io/specification/) (Open API Specification) and [RAML](https://raml.org/) (RESTful API Modeling Language). RAML is pretty cool, but OAS has bigger community and OAS became our choice. And unfortunately, we need to use outdated OAS2 format (aka "Swagger"), because OAS3 is not supported by numerous tools you will probably need it future. Contents -------- [](#contents) You can find in this repo: - Examples of swagger API documentation in OAS2, OAS3 in Yaml format. *It's a multi-document structure with cross-docs references, to keep things DRY (Don't Repeat Yourself)* - [Swagger UI](https://swagger.io/tools/swagger-ui/) viewer for API documentation - PHP tool to **merge multi-document yaml** to a single document. *Unfortunately available tools works only with single documents.* - PHP tool to **generate fake object examples** with [Faker](https://github.com/fzaninotto/Faker) library. Writing Docs ------------ [](#writing-docs) ### Setup project [](#setup-project) To start with - you can clone this repository to some webserver. It uses static html and javascript, so you don't need any special server configuration. You will need composer package manager on the server. ``` git clone https://github.com/justcoded/swagger-tools.git /path/to/docroot/swagger cd /path/to/docroot/swagger composer install ``` That's it, you can open `http://mydomain.com/swagger/` in browser and you will get a Swagger UI with our sample doc. *Or you can try to check swagger UI running nginx with docker like this:* ``` docker run -p 8080:80 --name swagger-tools -v ./:/usr/share/nginx/html:ro nginx ``` ### Create your docs [](#create-your-docs) Now let's go to the `examples` folder. You can copy some folder to start with. After that you will need to update `index.html` to point to your new docs by default: ``` window.onload = function() { // Build a system const ui = SwaggerUIBundle({ url: "./examples/jsonapi/swagger.yaml", ... ``` As already mentioned we use OAS2 format, specification can be found here: - - If you are new to the swagger format you will need to learn such declarations: - Definitions Object (for Models and Objects) - Path Object - for routes - Parameter Object - for defining parameters - Response Object - for response Docs structure we propose to use: ``` - routes/ # Routes/Paths definitions grouped by section - auth.yaml - users.yaml - models.yaml # Models/Requests definition - params.yaml # Params, which are similar for paths in different routes groups - responses.yaml # General responses definitions like 204, 401, 403, 404, 422, 500, etc. - swagger.yaml # Main file, which includes other files ``` Because of limitations of OAS2 format we need to list ALL routes inside main file: ``` paths: /auth/sign-in: $ref: "routes/auth.yaml#/paths/login" /auth/verify: $ref: "routes/auth.yaml#/paths/verify" /auth/password-reset: $ref: "routes/auth.yaml#/paths/resetPassword" ... ``` Having the examples I think all other things are self-explanatory. ### Swagger Editor [](#swagger-editor) We recommend to use WebStorm or PHPStorm (or any other Jetbrains IDE) to edit swagger yaml files. To have autocompletions on swagger identifiers and references you will need to install plugin called [Swagger Plugin](https://plugins.jetbrains.com/plugin/8347-swagger-plugin). ### JSON format [](#json-format) When you develop an API it's always a hard decision on what format JSON should be looks like. To solve this problem we suggest to follow JSONAPI specs: In general, it defines that we need to transfer data in a format like this: ``` { "data": [{ // collection or resource itself "type": 'resource type', "id": 'some id', "attributes": { // resource attribute }, "relationships": { 'relation name': { "data": { "type": "resource type", "id": "some id" } } // ... } }], "included": [{ // data for related resources "type": "related resource type", "id": "some id", "attributes": { // related resource data } // ... }], "meta": { // some other data like pagination info, tokens, etc. } } ``` This format is good for JavaScript libraries such as React.js, Vue.js and Angular, because it's super easy to populate scope based on resource types. JSONAPI has a lot of ready-to-use implementations: #### JSONAPI Format For Non-resource Requests [](#jsonapi-format-for-non-resource-requests) Unfortunately, this specification doesn't answer how to form non-resource requests. Usually these are some actions, for example "search". We suggest to define that we can transfer a document-type model of type "userInput", which can vary from route to route. Looks like this: ``` { "data": { "type": "userInput", "attributes": { // key/value pairs of user input data } } } ``` PHP Tools --------- [](#php-tools) - Merge multi-document swagger YAML documentation - Generate fake data to enums for mock servers ### Merge tool [](#merge-tool) ``` ./cli/swagger-merge.php examples/v2.0/swagger.yaml > merged-swagger2.yaml ``` ### Faker tool [](#faker-tool) Add to your properties x-faker attribute: ``` swagger: '2.0' definitions: User: type: object properties: id: type: integer format: int64 minimum: 1 email: type: string format: email x-faker: email first_name: type: string x-faker: firstName last_name: type: string x-faker: lastName ``` Run command: ``` ./cli/swagger-faker.php examples/merged/swagger2.yaml -n10 -r -c > swagger-faked.yaml ``` You will get: ``` definitions: User: type: object properties: id: type: integer format: int64 minimum: 1 email: type: string format: email x-faker: email enum: - muhammad.schuster@yahoo.com - hansen.rudy@nolan.com - nlittel@hotmail.com - gleason.araceli@witting.com - sreichert@hotmail.com - swift.dayna@kris.com - russel55@gmail.com - dicki.emery@hotmail.com - morris77@hotmail.com - lprice@yahoo.com first_name: type: string x-faker: firstName enum: - Denis - Donna - Elissa - Brandyn - Dino - Linda - Sadye - Kenneth - Michel - Theo ... required: - id - email - first_name - last_name - profile ``` Using this repo as dependency ============================= [](#using-this-repo-as-dependency) Of course, you can add this repository as dependency to your project, symlink swagger ui assets to your public repository and create your template inside your framework to print swagger ui interface, pointing to some generated doc. As an example we created Yii extension, wrapping our PHP tools: ### Health Score 42 — FairBetter than 90% of packages Maintenance42 Moderate activity, may be stable Popularity27 Limited adoption so far Community11 Small or concentrated contributor base Maturity72 Established project with proven stability Bus Factor1 Top contributor holds 87% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~477 days Recently: every ~504 days Total 6 Last Release 476d ago Major Versions 1.0.1 → 2.0.02020-11-24 v2.1.0 → v3.0.02023-02-23 PHP version history (2 changes)1.0PHP >=7.1.0 v3.0.0PHP >=8.0.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/af1a2fe7b505ad0881c589628c6a1f2a30213b9a27cc939b8bb60028764b733c?d=identicon)[justcoded](/maintainers/justcoded) --- Top Contributors [![aprokopenko](https://avatars.githubusercontent.com/u/1842666?v=4)](https://github.com/aprokopenko "aprokopenko (20 commits)")[![yvoitenko](https://avatars.githubusercontent.com/u/42643587?v=4)](https://github.com/yvoitenko "yvoitenko (3 commits)") --- Tags fakerswaggeropenapimerge ### Embed Badge ![Health badge](/badges/justcoded-swagger-tools/health.svg) ``` [![Health](https://phpackages.com/badges/justcoded-swagger-tools/health.svg)](https://phpackages.com/packages/justcoded-swagger-tools) ``` ### Alternatives [darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 2.9k34.0M112](/packages/darkaonline-l5-swagger)[darkaonline/swagger-lume OpenApi or Swagger integration to Lumen 3372.3M3](/packages/darkaonline-swagger-lume)[harmbandstra/swagger-ui-bundle Exposes swagger UI inside your Symfony project through a route (eg. /docs) 42867.3k](/packages/harmbandstra-swagger-ui-bundle)[jane-php/open-api-3 Generate a PHP Client API (PSR7/PSR18 compatible) given a OpenApi 3.x specification 201.4M87](/packages/jane-php-open-api-3)[psx/api Parse and generate API specification formats 37178.0k4](/packages/psx-api)[erasys/openapi-php Open API 3.0 builder and validation library for PHP that helps you write valid specs. 2080.3k5](/packages/erasys-openapi-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)