【轉】5分鍾了解Swagger

        </div>

        <div class="article-info-box">
            <div class="article-bar-top" style="height: 24px;">
                                                                                                                                                            
                  <div class="tags-box space">
                           
                                                                                                     
                                                                                            </div>
                                    </div>
            <div class="operating">
                                </div>
        </div>
    </div>
</div>
<article class="baidu_pl">
    <!--python安裝手冊開始-->
            <!--python安裝手冊結束-->
             <div id="article_content" class="article_content clearfix">
                                        <div class="article-copyright">
            <span class="creativecommons">
                <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">
                </a>
                <span>
                    版權聲明：本文為博主原創文章，遵循<a href="http://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="noopener"> CC 4.0 BY-SA </a>版權協議，轉載請附上原文出處鏈接和本聲明。                    </span>
                <div class="article-source-link2222">
                    本文鏈接：<a href="https://blog.csdn.net/i6448038/article/details/77622977">https://blog.csdn.net/i6448038/article/details/77622977</a>
                </div>
            </span>
                
            </div>
                                                <!--一個博主專欄付費入口-->
         
         <!--一個博主專欄付費入口結束-->
        <link rel="stylesheet" href="https://csdnimg.cn/release/phoenix/template/css/ck_htmledit_views-4a3473df85.css">
                                    <div id="content_views" class="markdown_views prism-atom-one-dark">
                <!-- flowchart 箭頭圖標 勿刪 -->
                <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
                    <path stroke-linecap="round" d="M5,0 0,2.5 5,5z" id="raphael-marker-block" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0);"></path>
                </svg>

隨着互聯網技術的發展，現在的網站架構基本都由原來的后端渲染，變成了：前端渲染、先后端分離的形態，而且前端技術和后端技術在各自的道路上越走越遠。
前端和后端的唯一聯系，變成了API接口；API文檔變成了前后端開發人員聯系的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。

其他API文檔工具

沒有API文檔工具之前，大家都是手寫API文檔的，在什么地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好壞。

書寫API文檔的工具有很多，但是能稱之為“框架”的，估計也只有swagger了。
在此先介紹一款其他的API文檔工具，叫rap，這玩意兒用一句話就能概括：解放生產力，代替手寫API的web工具。
RAP寫起來確實比手寫文檔要快，看看圖就知道：
可以選擇某個項目，寫針對某個項目的API

請看，可以填寫請求和相應的字段

還可以選擇字段對應的類型

類似的API文檔工具網上還有很多，但是能拿上台面的，不多。RAP是由阿里開發的，整個阿里都在用，還不錯。github地址為：https://github.com/thx/RAP
當然咯，rap不可能只有線上版本，肯定可以部署到私服上。
https://github.com/thx/RAP/wiki/deploy_manual_cn

swagger

rap挺好的，但是和swagger比起來有點輕量。
先看看swagger的生態使用圖：

其中，紅顏色的是swaggger官網方推薦的。

下面再細看看swagger的生態的具體內容：

swagger-ui

這玩意兒從名字就能看出來，用來顯示API文檔的。和rap不同的是，它不可以編輯。

點擊某個詳細API的可以試。

swagger-editor

就是一個在線編輯文檔說明文件（swagger.json或swagger.yaml文件）的工具，以方便生態中的其他小工具（swagger-ui）等使用。
左邊編輯，右邊立馬就顯示出編輯內容來。

編輯swagger說明文件使用的是yaml語法具體的內容可以去官網查看。

各種語言版本的根據annotation或者注釋生成swagger說明文檔的工具

目前最流行的做法，就是在代碼注釋中寫上swagger相關的注釋，然后，利用小工具生成swagger.json或者swagger.yaml文件。

目前官方沒有推出。github上各種語言各種框架各種有，可以自己搜吧搜吧，這里只說一個php相關的。
swagger-php :https://github.com/zircote/swagger-php

swagger-validator

這個小工具是用來校驗生成的文檔說明文件是否符合語法規定的。用法非常簡單，只需url地址欄，根路徑下加上一個參數url，參數內容是放swagger說明文件的地址。即可校驗。
例如：

docker hub地址為：https://hub.docker.com/r/swaggerapi/swagger-validator/
可以pull下鏡像來自己玩玩。

swagger-codegen

代碼生成器，腳手架。可以根據swagger.json或者swagger.yml文件生成指定的計算機語言指定框架的代碼。
有一定用處，Java系用的挺多。工業上應該不咋用。

mock server

這個目前還沒有找到很合適的mock工具，包括rap也好，其他API文檔工具也好，都做的不夠完善，大多就是根據說明文件，例如swagger.json等生成一些死的靜態的mock數據，不能夠根據限定條件：例如“只能是數字，必傳”等做出合理的回應。

                                </div>
            <link href="https://csdnimg.cn/release/phoenix/mdeditor/markdown_views-b6c3c6d139.css" rel="stylesheet">
                </div>
</article>

posted @ 2019-11-26 15:08  指掀濤瀾  閱讀( 19446)  評論( 0)  編輯  收藏