1 php swagger-php

Swagger 概念
The Best APIs are Built with Swagger Tools
Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.

---

文档地址：
https://swagger.io/
http://zircote.com/swagger-php/
https://packagist.org/packages/zircote/swagger-php

轻松实现PHP项目的Swagger Api 应用

1 下载 swagger-ui前端

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

2 使用默认项目 dist 文件夹

打开index.html，把其中的那一串url改成自己项目Api生成的json文件地址
http://localhost:8084/docs/openapi.yaml【第五步会生成】
(本地地址：/Users/mingyuan/Sites/service/docs/)

3 安装swagger-php，全局配置命令

composer global require zircote/swagger-php
生成命令 ~/.composer/bin/openapi
export PATH="~/.composer/vendor/bin:$PATH"

4 进入php项目， 编写swagger注释代码

/**
 * @OA\Info(
 *  title="Php API", 
 *  version="1.0",
 *  description="项目接口", 
 *  contact={
 *     "email": "jiangshui@qq.com"
 *  }, 
 *  license="license", 
 *  termsOfService="服务条款",
 * )
 * 
 * @OA\server(
 *      url="http://dev.jiangshui.cn/api",
 *      description="开发环境",
 * )
 * @OA\server(
 *      url="https://debug.jiangshui.cn/api",
 *      description="预发布环境",
 * )
 * @OA\server(
 *      url="https://pro.jiangshui.cn/api",
 *      description="正式环境【Warning】",
 * )
 * 
 */

   /**
     * @OA\Post(
     *     path="/af/friend/addFriend",tags={"Friend"},operationId="addFriend",summary="用户好友之间添加",
     *     @OA\Parameter(name="userid",in="path",required=true,@OA\Schema(type="number"),description="当前账号userid (被邀请)"),
     *     @OA\Parameter(name="friendid",in="path",required=true,@OA\Schema(type="number"),description="邀请人userid"),
     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="application/json",
     *             @OA\Schema(
     *                 example={"userid":2,"friendid":"3"}
     *             )
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="",
     *         @OA\MediaType(
     *             mediaType="application/json",
     *             @OA\Schema(
     *                example={"data":{}}
     *             )
     *         )
     *     ),
     * )
     */

5 执行命令，编译注释代码，生成openapi.yaml文档
openapi --format json /Users/mingyuan/Sites/service/application/controllers/ -o /Users/mingyuan/Sites/service/docs/

6 浏览器打开dist项目中index.html(资源路径有问题，需要自己配置一下)

image.png
image.png