Swagger 生成 PHP API 接口文档
标签（空格分隔）： php
1、概况
有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用。
有同学推荐了swagger+easymock，Swagger是一个简单但功能强大的API表达工具。 这里介绍使用swagger-php生成PHP API文档的方法。
2、安装与使用
2.1 安装swagger-php包
git clone /zircote/swagger-php.gitcomposer install
// 全局的composer global require zircote/swagger-php// 项目中composer global require zircote/swagger-php
2.2 laravel项目安装
使用L5 Swagger/DarkaOnLine/L5-Swagger
具体安装过程请参考此文档: /DarkaOnLin...
2.3 编写API注解
# 创建文件 demo/customer.php<?php/*** @OA\Info(title="My First API", version="0.1")*/class Customer{/*** @OA\Get(*path="/customer/info",*summary="用户的个人信息",*description="这不是个api接口,这个返回一个页面",*@OA\Parameter(name="userId", in="query", @OA\Schema(type="string"), required=true, description="用户ID"),*@OA\Response(*response="200",*description="An example resource"*)* )*/public function info(int $userId, string $userToken){}}
2.4 生成swagger API 文件
./swagger-php/bin/openapi demo -o ./docs
API 内容如下:
# docs/openapi.yamlopenapi: 3.0.0info:title: 'My First API'version: '0.1'paths:/customer/info:get:summary: 用户的个人信息description: '这不是个api接口,这个返回一个页面'operationId: 'Customer::info'parameters:-name: userIdin: querydescription: 用户IDrequired: trueschema:type: stringresponses:'200':description: 'An example resource'
3、展示
git clone /swagger-api/swagger-ui.gitcomposer install
直接通过Dockerfile构建、启动项目， 或者使用docker-compose进行服务管理。
version: '2'services:swagger-ui:build: .ports:- "8080:8080"volumes:- ./dist/:/usr/share/nginx/html/restart: on-failure
访问 http://localhost:8080/ 即可到swagger编辑器预览界面。
./swagger-php/bin/openapi demo -o ./swagger-ui/dist/
将 api文档输出值swagger ui的根目录下，可通过 http://localhost:8080/openapi.yaml 访问此api文档。
执行Explore结果如图:
