18. PHPer x API document x Swagger API

想当一个 Good PHPer，不但要写程序、写注解还要写 API 文件，想到要维护三个地方工程师就累了。
要是能从程序码或注解产生文件就好了呢。

今天...又是...拿出我珍藏的...旧文

Swagger API 是一个 REST API 的编辑、视觉化、自动产生工具。
你可以透过 yaml 或 json 格式的方式来产生视觉化的 API 文件。

我们将透过这个工具以及注解，将 Laravel API 直接转换成文件。

安装

1.去 github 上找一个看起来简单的 swagger api 套件来安装

例如我这个范例使用 zircote/swagger-php

2.为你的 api functions 加 annotations

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/fizzbuzz",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */
public function index (Request $num)
{
    $result = $this->testService->getFizzBuzz($num);
    return $result;
}

产生方法一

写一个脚本，再手动上传

1.run generator

php generateApi.php > myApi.yml

2.发布 API

把产生出来的 yaml 手动丢上 swagger hub（要注册帐号，免费版有限制）

产生方法二

用 Swagger UI + api 产生一个 html