README

Hyperf Swagger

If You Like This Please Give Me Star

Install

The preferred way to install this extension is through composer.

Either run

composer require lengbin/hyperf-swagger

or add

"lengbin/hyperf-swagger": "*"

to the require section of your composer.json file.

Request

"zircote/swagger-php": "2.0.14"

If want to test api . Please look annocation

Publish

      
php ./bin/hyperf.php vendor:publish lengbin/hyperf-swagger

Configs

	// 静态资源 配置 /config/autoload/server.php
    
    return [
        ......
        
        settings => [
            ......
        
            // 静态资源
            'document_root' => BASE_PATH . '/public',
            'static_handler_locations' => ['/'],
            'enable_static_handler' => true,

            ......
        ],

        ......
    ]
	// 发布后生成配置文件
	// 路径为 /config/autoload/swagger.php
	
	return [
		//static path (dir name) , eg:  'swagger' or '/swagger'
		'path'               => 'swagger',
		// generator annotation file path
		'filePath'           => BASE_PATH . '/runtime/swagger',
		//api url
		'url'                => '/swagger/api',
		//  swagger version , support 2, 3, default 3
		'version'            => \Lengbin\Hyperf\Swagger\Swagger::SWAGGER_VERSION_DEFAULT,
		// The OAuth Configration
		'oauthConfiguration' => [],
		// generator config
		'generator'          => [
			// http method , eg: get, post, delete put
			'httpMethods'     => [],
			// content-type, eg: "application/json", "application/x-www-form-urlencoded"
			'contentTypes'    => [],
			//Parameters of the position, eg: "formData", "path", "query", "header", "body"
			'parameterIns'    => [],
			// Parameter type, eg: "string", "number", "integer", "boolean", "file"
			'parameterTypes'  => [],
			// definition type, eg: "array" , "object" , "string", "number", "integer", "boolean"
			'definitionTypes' => [],
			// default value
			'default'         => [
				// open response template
				"openResponseTemplate" => false,
				/**
				 * response default definition template, eg:
				 *'responseTemplate' => [
				 *  'code' => 0,
				 *  'message' => 'Success',
				 *  'data' => '{{replace}}',
				 *],
				 */
				'responseTemplate'     => [],
				/**
				 * parameters
				 * [
				 *  [
				 *      "name" => "token",
				 *      "description" => "Token",
				 *      "in" => "header",
				 *      "type" => "string",
				 *      "ref" => "",
				 *      "required" => "yes", // "yes" or "no"
				 *      "default" => "1",
				 *  ]
				 * ]
				 */
				'parameters'           => [],
				/**
				 * responses
				 * [
				 *  [
				 *   "status"      => 200,
				 *   "description" => "success",
				 *   "type"        => "object",
				 *   "ref"         => "SuccessDefault",
				 *   "example"     => '',
				 *  ]
				 * ]
				 */
				'responses'            => [
					[
						"status"      => 200,
						"description" => "success",
						"type"        => "object",
						"ref"         => "SuccessDefault",
						"example"     => '',
					],
					[
						"status"      => "default",
						"description" => "请求失败， http status 强行转为200, 通过code判断",
						"type"        => "object",
						"ref"         => "ErrorDefault",
						"example"     => '',
					],
				],
				/**
				 * definition select template, eg:
				 */
				'definitionTemplate'   => [
					'default' => [],
					'page'    => [
						[
							'property'    => 'list',
							'description' => '列表',
							'type'        => 'array',
							'ref'         => '',
							'example'     => '',
						],
						[
							'property'    => 'currentPage',
							'description' => '当前分页',
							'type'        => 'integer',
							'ref'         => '',
							'example'     => 1,
						],
						[
							'property'    => 'pageSize',
							'description' => '分页大小',
							'type'        => 'integer',
							'ref'         => '',
							'example'     => 10,
						],
						[
							'property'    => 'totalPage',
							'description' => '总分页',
							'type'        => 'integer',
							'ref'         => '',
							'example'     => 1,
						],
						[
							'property'    => 'totalCount',
							'description' => '总条数',
							'type'        => 'integer',
							'ref'         => '',
							'example'     => 11,
						],
					],
				],
			],
		],
	];

访问接口 /swagger/api，如果配置文件修改filePath路径，将在 project/runtime/swagger 文件下生成3个默认文件

swagger.php

error.php （一些自定义参数demo，可以删除）

tag.php （分类注释demo，可以删除）修改 swagger.php， host为您的域名，可以模拟测试

Usage

<?php

namespace App\Controller;

use Hyperf\Di\Annotation\Inject;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\GetMapping;
use Lengbin\Hyperf\Swagger\Swagger;

/**
 * Class SwaggerController
 * @package App\Controller
 * @Controller()
 */
class SwaggerController extends AbstractController
{

    /**
     * @Inject()
     * @var Swagger
     */
    public $swagger;

    /**
     * swagger ui 
     * @GetMapping(path="/swagger")
     */
    public function index()
    {
        return $this->swagger->html();
    }

    /**
     * swagger open api
     * @GetMapping(path="/swagger/api")
     */
    public function api()
    {
        // 扫码目录path
        $path = dirname(__DIR__) . DIRECTORY_SEPARATOR . 'swagger';
        return $this->swagger->api([
            $path,
        ]);
    }
    
    /**
     * swagger web -> generator annotation
     * @GetMapping(path="/swagger/generator")
     */
    public function generator()
    {
        return $this->swagger->generator($this->request);
    }

    /**
     * swagger web api
     * @RequestMapping(path="/swagger/annotation", methods={"GET", "POST"})
     */
    public function annotation()
    {
        // 扫码目录path, 生成注释文档目录
        $path = dirname(__DIR__) . DIRECTORY_SEPARATOR . 'swagger';
        return ['code' => 0, 'message' => 'Success', 'data' => $this->swagger->annotation($this->request, $path)];
    }

}

Todo list

Swagger Ui2
Swagger Ui3
Read Swaager Annotation Generator Openapi
Swaager Generator Annotation
Other Swagger Ui Theme

lengbin / hyperf-swagger

Maintainers

Details