Swagger API 文档生成

优质

小牛编辑

188浏览

2023-12-01

支持在项目中使用 Swagger 注解语法，运行命令，生成 Swagger 文件。

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。

Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。

Swagger 是一种通用的，和编程语言无关的 API 描述规范。

imi-apidoc 基于 zircote/swagger-php 开发，100% 支持写法。

Github: https://github.com/imiphp/imi-apidoc

Composer

本项目可以使用composer安装，遵循psr-4自动加载规则，在你的 composer.json 中加入下面的内容:

{
    "require": {
        "imiphp/imi-apidoc": "^1.0.0"
    }
}

然后执行 composer update 安装。

使用说明

可以参考 example、tests 目录示例。

项目配置文件：

[
    'components'    =>  [
        'ApiDoc'  =>  'Imi\ApiDoc',
    ],
]

Swagger 书写文档说明：https://zircote.github.io/swagger-php/Getting-started.html

Demo:

<?php
namespace ImiApp\ApiServer\Controller;

use Imi\Server\Route\Annotation\Route;
use Imi\Server\Route\Annotation\Action;
use Imi\Controller\SingletonHttpController;
use Imi\Server\Route\Annotation\Controller;

/**
 * @OA\Info(title="My First API", version="0.1")
 * @Controller("/")
 */
class IndexController extends SingletonHttpController
{
    /**
     * @Action
     * @Route("/")
     * 
     *
     * @return void
     */
    public function index()
    {

    }

    /**
     * @Action
     * @Route(url="login", method="POST")
     *
     * @param string $username 用户名
     * @param integer $password 密码
     * 
     * @return void
     */
    public function login(string $username, int $password)
    {

    }

    /**
     * @Action
     * @Route("register")
     * @OA\Get(
     *     path="/register",
     *     @OA\Response(response="200", description="An example resource")
     * )
     *
     * @param string $username 用户名
     * @param integer $password 密码
     * @param string $birthday 生日
     * 
     * @return void
     */
    public function register(string $username, int $password
    , string $birthday)
    {

    }

    /**
     * @Action
     *
     * @param int $id
     * @return void
     */
    public function get(int $id)
    {

    }

}

imi-apidoc 会根据 @Route 注解、@param 注释，自动补足相关信息。让你不必为每个接口都书写 Swagger 注解，提升开发效率。

当然，如果希望更加个性化的信息设置，还是要自己去书写的！

生成命令：

Yaml 格式: imi doc/api -to api.yml

Json 格式: imi doc/api -to api.json

指定扫描的命名空间：imi doc/api -to api.json -namespace "ImiApp\Controller1,ImiApp\Controller2"

效果：

avatar