Swagger PHP Usage Guide ____php

Swagger PHP Usage Guide

First say what is swagger, the use of swagger is convenient and graceful presentation of various definitions of interface API, generate API documents, including parameters, paths and so on. Sometimes the backend changes the parameters of the API or other settings, the front-end directly look at the swagger UI can be convenient for project management and team collaboration.

The official website is http://swagger.io/

How does this thing work? To put it plainly is to install the Swagger Suite, and then write the comments in the API code, use the swagger back-end program running API to extract annotations, generate a JSON file, then customs swagger the front end to beautify, collation JSON data.

To use the swagger to install 2 things, the front segment, used to display the backend, used to generate JSON

# #1, pre-installation section

Swagger-ui Download

1	git clone https://github.com/swagger-api/swagger-ui.git

After downloading to find the Dist directory, open the index.html of which a string of URLs changed to their own, such as Http://localhost/yii2/swagger-docs/swagger.json

$ (function () {
      var url = window.location.search.match (/url= ([^&]+)/);
      if (URL && url.length > 1) {
        URL = decodeuricomponent (url[1]);
      } else {
        URL = "Http://localhost/yii 2/swagger-docs/swagger.json ";
      }

can also adjust the interface into Chinese, let go of the JS file annotation can be

1 2 3

<script src= ' lang/translator.js ' type= ' text/javascript ' ></script> <!--<script src= ' lang/ru.js ' t Ype= ' Text/javascript ' ></script>--> <script src= ' lang/zh-cn.js ' type= ' text/javascript ' Pt>

Then open the URL can see the front-end interface, should be no content, because has not generated swagger.json, the creation of a good URL after you set up a role, direct access to the front end is good

Http://localhost/yii2/swagger-ui/dist/index.html

# #2, install back end

1	git clone https://github.com/zircote/swagger-php.git

Because I used yii2, I used composer to install it.

"Require": {"zircote/swagger-php": "*"}

Composer update later, or direct command line, see https://github.com/zircote/swagger-php

Dcdemacbook-pro:yii2 dc$ php Composer.phar require zircote/swagger-php

I put the swagger-php in the root directory and then use the official examples to generate the test JSON.

CD swagger-php
mkdir doc 
php swagger.phar examples-o doc

The "-O" front represents the API source directory, which is the API document for which directory you want to generate, and your project code directory. Which path is generated after "-O"

I did not enter the swagger-php below, directly to the command line, any path can be performed to generate JSON operations

php/users/dc/www/yii2/vendor/zircote/swagger-php/bin/swagger/users/dc/www/yii2/vendor/zircote/swagger-php/ Examples-o/users/dc/www/yii2/swagger-docs

Then look at the http://localhost/yii2/swagger-ui/dist/index.html and generate the API documentation

Preparation is done, then write code comments on the line, comments how to write? Refer to official documentation http://zircote.com/swagger-php/annotations.html

Like model.

/**
* @SWG \model (
* id= "VPS",
* required= "[' type ', ' hostname ']",
*  @SWG \property (name= " Hostname ", type=" string "),
*  @SWG \property (name=" label ", Type=" string "),
*  @SWG \property (name=" Type ", type=" string ", enum=" [' VPS ', ' dedicated '] ")
* *)/
class Hostvps extends Host implements Resourceinterface
{
    //...
}

Like controller.

/**
 * @SWG \resource (
 *  basepath= "Http://skyapi.dev",
 *  resourcepath= "/vps",
 *  @SWG \ API (
 *   path= "/vps",
 *   @SWG \operation (
 *    method= "Get",
 *    type= "Array",
 *    summary= "Fetch VPS Lists",
 *    nickname= "Vps/index",
 *    @SWG \parameter (
 *     name= "Expand",
 *     description= "Models to expand",
 *     paramtype= "Query",
 *     type = "string",
 *     defaultvalue= "vps,os_template" *) *) *)
 * /
 class Vpscontroller extends Controller
 {
     //...
 }

Also see an integration that integrates swagger into laravel. GitHub address is this https://github.com/slampenny/Swaggervel, but this can not be used Git clone way to follow, configure too much trouble, with composer Bar

Composer require "Jlapp/swaggervel:dev-master"

Next Jlapp\swaggervel\swaggervelserviceprovider copy this sentence to the top of app/config/app.php's providers array, and then

PHP Artisan Vender:publish

This step copies the related files including the Swagger UI to the Laravel framework public. OK, already good, try to access the root directory, such as Www.1.com/api-docs try, the appearance of the interface is successful. Without from, look at the routing of Laravel with an order.

PHP Artisan route:list

The top 2 is the route you just added. Refreshing the page is not found blank. To produce JSON requires you to write @swg comments, and then laravel the app directory any of the following files can be written, generally we only need to write model and controller, this plugin will scan this directory production JSON file.

=====================================

Do you want to manually generate the JSON file each time you change the API code comments? Too much trouble, wrote a controller, each visit to the Swagger-ui of this controller, Sir into JSON and then jump to the UI page

$b 2broot = Yii::getalias (' @b2broot ');
$swagger = \swagger\scan ($b 2broot. ' /myapi ');
$json _file = $b 2broot. ' /swagger-docs/swagger.json ';
$is _write = file_put_contents ($json _file, $swagger);
if ($is _write = = True) {
   $this->redirect (' http://localhost/yii2/swagger-ui/dist/index.html ');
}

Reference from http://blog.didibird.com/2015/06/23/swagger-ui-tutorials-api-documentation-generation-artifact/