Swagger 生成 PHP API 接口文档详细步骤

现在程序员写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用。

Swagger是一个简单但功能强大的API表达工具。 这里介绍使用swagger-php生成PHP API文档的方法。

1.安装swagger-php包

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

composer install

// 全局的

composer global require zircote/swagger-php

// 项目中

composer global require zircote/swagger-php

2.laravel项目安装

使用 L5 Swagger https://github.com/DarkaOnLine/L5-Swagger

3.编写API注解

# 创建文件 demo/customer.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)

{

}

}

4.生成swagger API 文件

./swagger-php/bin/openapi demo -o ./docs API 内容如下:

# docs/openapi.yaml

openapi: 3.0.0

info:

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'

5.展示

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

composer 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 结果如图

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。