CodeIgniter+swagger实现 PHP API接口文档自动生成功能自动生成ci RESTFUL api接口文档

最新推荐文章于 2023-08-31 17:07:45 发布

置顶爱吃榴莲的橙子

最新推荐文章于 2023-08-31 17:07:45 发布

阅读量3.2k

点赞数 1

分类专栏： php swagger CodeIgniter 文章标签： swagger 自动生成接口文档 php

本文链接：https://blog.csdn.net/u011477914/article/details/85246355

版权

php 同时被 3 个专栏收录

31 篇文章 1 订阅

订阅专栏

CodeIgniter

5 篇文章 0 订阅

订阅专栏

swagger

1 篇文章 0 订阅

订阅专栏

一、安装swagger

1、首先需要有composer，没有的自行百度安装

2、下载swagger，打开网站https://packagist.org/packages/zircote/swagger-php，根据自己的php版本选择对应的版本号

3、安装：PhpStorm打开项目，然后在左下角

点击Terminal弹窗黑窗口然后在里面输入：composter require zircote/swagger-php 2.0.13 回车，开始安装

4、项目目录

5、使用，安装成功后，在CodeIgniter控制器中(D:/wwwroot/CodeIgniter/site/admin/application/controllers/)新建Swagger.php

<?php
/**
 * Created by PhpStorm.
 * User: jason
 * Date: 2018/12/20
 * Time: 13:44
 * api 接口文档
 */

class Swagger extends CI_Controller {

    /**
     * 构造函数
     *
     * 数据模型，扩展库，辅助方法初始化
     */
    public function __construct() {
        parent::__construct();
    }

    public function index(){
        //接口php文件存放的本地路径 要找到入口文件index.php的路径 （D:/wwwroot/CodeIgniter/font/api/application/controllers）
        $openapi = swagger\scan( __DIR__.'/font/api/application/controllers');
        //最后生成的json文件存放路径（例子：D:/wwwroot/CodeIgniter/public/asset/swagger/swagger-docs/swagger.json）
        $jasonFile = __DIR__.'/public/asset/swagger/swagger-docs/swagger.json';
        //每次自动生成json文件
        file_put_contents($jasonFile,$openapi);
        //加载视图
        $this->load->view('swagger','');
    }
}

6、然后创建视图文件（D:/wwwroot/CodeIgniter/site/admin/views/controllers/swagger.php）,这里要下载（swagger-ui-master.zip，解压到相应目录，然后把dist中的index.html文件中的内容复制到swagger.php中，再把json文件路径改成自己的就可以），这样每次修改api接口注释信息的时候就会自动生成json文件

路径：域名/swagger/swagger-docs/swagger.json

  var url = "https://api.aa.com/asset/swagger/swagger-docs/swagger.json";

<?php define('SITE_FILE', 'https://api.aa.com/asset/');?>
<!DOCTYPE html>
<html>
<head>
    <title>接口文档</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <!--[if lt IE 9]>
    <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
    <!--style type="text/css"></style-->
    <link href="<?php echo SITE_FILE; ?>swagger/dist/css/index.css" rel="stylesheet"/>
    <link href='<?php echo SITE_FILE; ?>swagger/dist/css/standalone.css' rel='stylesheet'/>
    <link href='<?php echo SITE_FILE; ?>swagger/dist/css/api-explorer.css' rel='stylesheet' type='text/css'/>
    <link href='<?php echo SITE_FILE; ?>swagger/dist/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/jquery.slideto.min.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/jquery.wiggle.min.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/handlebars-2.0.0.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/underscore-min.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/backbone-min.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/swagger-ui.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/jsoneditor.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/highlight.7.3.pack.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/marked.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/swagger-oauth.js' type='text/javascript'></script>
    <script src='<?php echo SITE_FILE; ?>swagger/dist/lib/bootstrap.min.js' type='text/javascript'></script>
    <script type="text/javascript">
        jQuery.browser = jQuery.browser || {};
        (function () {
            jQuery.browser.msie = jQuery.browser.msie || false;
            jQuery.browser.version = jQuery.browser.version || 0;
            if (navigator.userAgent.match(/MSIE ([0-9]+)\./)) {
                jQuery.browser.msie = true;
                jQuery.browser.version = RegExp.$1;
            }
        })();

        $(function () {
            var url = "<?php echo SITE_FILE; ?>swagger/dahua-docs/swagger.json";
            window.swaggerUi = new SwaggerUi({
                url: url,
                dom_id: "swagger-ui-container",
                supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
                onComplete: function (swaggerApi, swaggerUi) {
                    if (typeof initOAuth == "function") {
                        initOAuth({
                            clientId: "ffe7748a-3a3f-4860-a02a-42ab08e4fde2",
                            realm: "realm",
                            appName: "Swagger"
                        });
                    }

                    $('pre code').each(function (i, e) {
                        hljs.highlightBlock(e)
                    });

                    if (swaggerUi.options.url) {
                        $('#input_baseUrl').val(swaggerUi.options.url);
                    }
                    if (swaggerUi.options.apiKey) {
                        $('#input_apiKey').val(swaggerUi.options.apiKey);
                    }

                    $("[data-toggle='tooltip']").tooltip();

                    addApiKeyAuthorization();
                },
                onFailure: function (data) {
                    log("Unable to Load SwaggerUI");
                },
                docExpansion: "none",
                sorter: "alpha"
            });

            function addApiKeyAuthorization() {
                var key = encodeURIComponent($('#input_apiKey')[0].value);
                if (key && key.trim() != "") {
                    var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("Authorization", "Bearer " + key, "header");
                    window.swaggerUi.api.clientAuthorizations.add("key", apiKeyAuth);
                    log("added key " + key);
                }
            }

            $('#input_apiKey').change(addApiKeyAuthorization);
            window.swaggerUi.load();
            function log() {
                if ('console' in window) {
                    console.log.apply(console, arguments);
                }
            }
        });
    </script>
    <script type="text/javascript">
        $(function () {
            $(window).scroll(function () {
                var sticky = $(".sticky-nav");

                i(sticky);
                r(sticky);

                function n() {
                    return window.matchMedia("(min-width: 992px)").matches
                }

                function e() {
                    n() ? sticky.parents(".sticky-nav-placeholder").removeAttr("style") : sticky.parents(".sticky-nav-placeholder").css("min-height", sticky.outerHeight())
                }

                function i(n) {
                    n.hasClass("fixed") || (navOffset = n.offset().top);
                    e();
                    $(window).scrollTop() > navOffset ? $(".modal.in").length || n.addClass("fixed") : n.removeClass("fixed")
                }

                function r(e) {
                    function i() {
                        var i = $(window).scrollTop(), r = e.parents(".sticky-nav");
                        return r.hasClass("fixed") && !n() && (i = i + r.outerHeight() + 40), i
                    }

                    function r(e) {
                        var t = o.next("[data-endpoint]"), n = o.prev("[data-endpoint]");
                        return "next" === e ? t.length ? t : o.parent().next().find("[data-endpoint]").first() : "prev" === e ? n.length ? n : o.parent().prev().find("[data-endpoint]").last() : []
                    }

                    var nav = e.find("[data-navigator]");
                    if (nav.find("[data-endpoint][data-selected]").length) {
                        var o = nav.find("[data-endpoint][data-selected]"),
                            a = $("#" + o.attr("data-endpoint")),
                            s = a.offset().top,
                            l = (s + a.outerHeight(), r("next")),
                            u = r("prev");
                        if (l.length) {
                            {
                                var d = $("#" + l.attr("data-endpoint")), f = d.offset().top;
                                f + d.outerHeight()
                            }
                            i() >= f && c(l)
                        }
                        if (u.length) {
                            var p = $("#" + u.attr("data-endpoint")),
                                g = u.offset().top;
                            v = (g + p.outerHeight(), 100);
                            i() < s - v && c(u)
                        }
                    }
                }

                function s() {
                    var e = $(".sticky-nav [data-navigator]"),
                        n = e.find("[data-endpoint]").first();
                    n.attr("data-selected", "");
                    u.find("[data-selected-value]").html(n.text())
                }

                function c(e) {
                    {
                        var n = $(".sticky-nav [data-navigator]");
                        $("#" + e.attr("data-endpoint"))
                    }
                    n.find("[data-resource]").removeClass("active");
                    n.find("[data-selected]").removeAttr("data-selected");
                    e.closest("[data-resource]").addClass("active");
                    e.attr("data-selected", "");
                    sticky.find("[data-selected-value]").html(e.text())
                }
            });
        });
    </script>

    <script type="text/javascript">
        $(function () {
            $("[data-toggle='tooltip']").tooltip();
        });
    </script>

</head>
<body class="page-docs" style="zoom: 1;">
<header class="site-header">
    <nav role="navigation" class="navbar navbar-default">
        <div class="container">
            <div class="navbar-header">
                <button type="button" data-toggle="collapse" data-target="#navbar-collapse" class="navbar-toggle"><span class="sr-only">Toggle navigation</span><span class="icon-bar"></span><span class="icon-bar"></span><span class="icon-bar"></span></button>
                <h1 class="navbar-brand"><a href="#"><span>接口文档</span></a></h1>
            </div>
            <div id="navbar-collapse" class="collapse navbar-collapse">
                <ul class="nav navbar-nav navbar-left">
                    <li class="li-why"><a href="#" style="font-size: 25px; padding-left: 0px">接口文档</a></li>
                </ul>
            </div>
        </div>
    </nav>
</header>

<section class="content">
    <div id="api2-explorer">
        <div class="swagger-section page-docs" style="zoom: 1">
            <div class="main-section">
                <div id="swagger-ui-container" class="swagger-ui-wrap">
                </div>
            </div>
        </div>
    </div>
</section>
</body>
</html>

二、使用swagger

可以参考这篇博客内容写的还是比较全的（https://laravel-china.org/index.php/topics/7430/how-to-write-api-documents-based-on-swagger-php）

我这简单介绍下：

1、在接口控制器目录下创建/api/application/controllers/swagger.php，写API 描述信息

<?php
/*
 * @SWG\Swagger(
 *     swagger="2.0",schemes={"https"},host="api.aa.com",basePath="/api",
 *     @SWG\Info(version="2.0",title="官网接口文档",description="官网2.0版本内部口文档")
 *     )
*/

2、在其他接口文件GIT提交

<?php

class Product ectends restful{

/*     
 * @SWG\Get(
 *     path="/product/menu/id/{id}",
 *     summary="产品类别列表接口",
 *     description="返回包含产品类别列表数据信息。",
 *     tags={"product"},
 *     @SWG\Parameter(
 *          name="id",
 *          in="path",
 *          default="5037",
 *          required=true,
 *          description="产品类别id",
 *          type="number"),
 *     @SWG\Response(response=200,description="OK")
 * )
*/
public menu_get(){

}


}

3、Post提交

 * @SWG\Post(
     *     path="/product/product_select",
     *     summary="产品选型接口",
     *     description="返回包含产品选型数据。",
     *     consumes={"application/x-www-form-urlencoded"},
     *     tags={"product"},
     *     @SWG\Parameter(
     *          name="id",
     *          in="formData",
     *          required=true,
     *          default="5037",
     *          description="产品栏目id",
     *          type="number"),
     *       @SWG\Parameter(
     *          name="type",
     *          in="formData",
     *          required=true,
     *          default="1",
     *          description="产品类型 0普通 1小众 2特殊 3与普通二级类别不同",
     *          type="number"),
     *       @SWG\Parameter(
     *          name="child",
     *          in="formData",
     *          default="5077",
     *          description="产品下级栏目id",
     *          type="number"),
     *      @SWG\Parameter(
     *          name="searchIds",
     *          in="formData",
     *          required=false,
     *          description="选型数据:10951,10961,10971",
     *          default="",
     *          type="string"
     *      ),
     *     @SWG\Response(response=200,description="OK")
     * )