Swagger 生成 PHP API 接口文档

Swagger 生成 PHP API 接口文档标签（空格分隔）： php1、概况有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用。有同学推荐了swagger+easymock，Swagger是一个简单但功能强大的API表达工具。 这里介绍使用swagger-php生成PHP API文档的方法。2、安装与使用2.1 安装swagger-php包git clone https://github.com/zircote/swagger-php.gitcomposer install// 全局的composer global require zircote/swagger-php// 项目中composer global require zircote/swagger-php2.2 laravel项目安装使用 L5 Swagger https://github.com/DarkaOnLine/L5-Swagger具体安装过程请参考此文档: https://github.com/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 ./docsAPI 内容如下:# 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: userId in: query description: 用户ID required: true schema: type: string responses: ‘200’: description: ‘An example resource'3、展示git clone https://github.com/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 结果如图:4、参考资料Swagger 生成 PHP restful API 接口文档如何编写基于 Swagger-PHP 的 API 文档https://github.com/zircote/swagger-phphttps://github.com/swagger-api/swagger-uiEasy MockLaravel（PHP）使用Swagger生成API文档不完全指南