imiphp/imi-apidoc

imi 框架 HTTP API 文档生成器,支持 Swagger!

v2.1.11 2023-12-08 08:44 UTC

README

Latest Version Php Version Swoole Version IMI License

介绍

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

Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。

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

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

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

本仓库仅用于浏览,不接受 issue 和 Pull Requests,请前往:https://github.com/imiphp/imi

Composer

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

{
    "require": {
        "imiphp/imi-apidoc": "~2.0.0"
    }
}

然后执行 composer update 安装。

使用说明

可以参考 exampletests 目录示例。

项目配置文件:

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

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

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"

效果:

免费技术支持

QQ群:17916227 点击加群,如有问题会有人解答和修复。

运行环境

版权信息

imi-apidoc 遵循 MIT 开源协议发布,并提供免费使用。

捐赠

开源不求盈利,多少都是心意,生活不易,随缘随缘……