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

﹏ヽ暗。殇╰゛Y 2022-04-02 04:37 494阅读 0赞

# 一、安装swagger #

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

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTE0Nzc5MTQ_size_16_color_FFFFFF_t_70][]

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

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

4、项目目录

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTE0Nzc5MTQ_size_16_color_FFFFFF_t_70 1][]

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">
        
        
        <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][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")
         * )

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTE0Nzc5MTQ_size_16_color_FFFFFF_t_70 2][]

[https_packagist.org_packages_zircote_swagger-php]: https://packagist.org/packages/zircote/swagger-php
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTE0Nzc5MTQ_size_16_color_FFFFFF_t_70]: /images/20220402/15cb273c390749129381e0af5afdae2c.png
[20181225131934163.png]: https://img-blog.csdnimg.cn/20181225131934163.png
[20181225132124860.png]: /images/20220402/790c33afd8ee43b5acd8b39849ea1ac8.png
[zircote]: https://packagist.org/packages/zircote/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTE0Nzc5MTQ_size_16_color_FFFFFF_t_70 1]: /images/20220402/f499b9714246408893b19d25c427171d.png
[swagger-ui-master.zip]: https://download.csdn.net/download/u011477914/10874935
[https_laravel-china.org_index.php_topics_7430_how-to-write-api-documents-based-on-swagger-php]: https://laravel-china.org/index.php/topics/7430/how-to-write-api-documents-based-on-swagger-php
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTE0Nzc5MTQ_size_16_color_FFFFFF_t_70 2]: /images/20220402/a453561852f04ec1a7f5ab3144709a6a.png