Web服務開發：Spring集成Swagger，3步

Web服務開發：Spring集成Swagger，3步自動生成API文檔

錄：

1，Spring Boot集成Swagger

2，Swagger接口文檔頁面

3，常見問題和解決方法

在Sping開發REST接口服務時，API文檔是不可缺少的一個重要部分。Swagger框架定義了完整的REST接口文檔規范，提供了強大的頁面測試功能，能夠調試和可視化API接口服務，并且將文檔融合到代碼中，讓維護文檔和修改代碼整合為一體，使得修改代碼邏輯的同時方便的修改文檔說明。

Spring集成Swagger只需3步配置，就能在線生成接口文檔，調試API功能。

代碼下載：https://github.com/jextop/StarterApi/

一，Spring Boot集成Swagger

1. 在pom.xml中添加Swagger依賴

2. 添加SwaggerConfig.java，配置文檔信息和掃描包路徑

3. （可選）代碼中引用Swagger注解，增加接口文檔。

- 不添加這些注解時，Swagger自動生成在線文檔將使用默認信息。

- 修改代碼功能邏輯時，同時維護文檔信息。

二，啟動項目，打開文檔頁面

1. http://localhost:8011/swagger-ui.html

2. 展開API信息，點擊按鈕”Try it out!”，調試接口功能。

三，常見問題和解決方法

l 增加@Api(tags={“xxx中文”})，Swagger文檔頁面中點擊接口名稱無法展開詳情？

解決：在pom.xml中配置maven依賴使用Swagger2.7.0或以后版本

原因：Swagger2.7.0修復了tags對中文的支持

halApi開源接口框架

讀音：派框架，官網：https://www.phalapi.net/

PhalApi是一個PHP輕量級開源接口框架，致力于快速開發接口服務。支持HTTP/SOAP/RPC等協議，可用于搭建接口/微服務/RESTful接口/Web Services。承諾永久免費，可用于商業用途。

它支持自動生成接口文檔、自動進行參數校驗、自動生成單元測試代碼、自動擁有CURD數據接口、自動安裝程序，讓接口開發更簡單、更高效、更專業。

PhalApi官網截圖：

在線示例

使用PhalApi開源接口框架，能快速開發編寫你的API接口，并能自動生成在線接口文檔。

在線示例：

在線接口文檔：http://demo.phalapi.net/docs.php
接口詳情文檔（以默認接口為例）：http://demo.phalapi.net/docs.php?service=App.Site.Index&detail=1&type=fold
默認接口服務：http://demo.phalapi.net/?s=App.Site.Index

PhalApi會根據你編寫的接口的參數配置和代碼注釋，自動實時生成在線接口文檔。接口列表頁效果類似如下：

PhalApi還支持在線接口測試、請求示例說明、生成離線版HTML接口文檔、實時更新。接口文檔詳情頁效果類似如下：

快速安裝

composer一鍵安裝

使用composer創建項目的命令，可實現一鍵安裝。

$ composer create-project phalapi/phalapi

溫馨提示：關于composer的使用，請參考Composer 中文網 / Packagist 中國全量鏡像。

手動下載安裝

或者，也可以進行手動安裝。將此Git項目代碼下載解壓后，進行可選的composer更新，即：

$ composer update

部署

Nginx配置

如果使用的是Nginx，可參考以下配置。

server {
    listen 80;
    server_name dev.phalapi.net;
    # 將根目錄設置到public目錄
    root /path/to/phalapi/public;
    charset utf-8;


    location / {
        index index.php;
    }


    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        # 根據當前環境，選擇合適的通訊方式
        # fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

配置時需要將網站根目錄設置到public目錄，配置保存后重啟nginx。

溫馨提示：推薦將訪問根路徑指向/path/to/phalapi/public。

數據庫配置

如何使用的是MySQL數據庫，參考修改./config/dbs.php數據庫配置。

return array(
    /**
     * DB數據庫服務器集群 / database cluster
     */
    'servers'=> array(
        'db_master'=> array(                       // 服務器標記 / database identify
            'type'=> 'mysql',                 // 數據庫類型，暫時只支持：mysql, sqlserver / database type
            'host'=> '127.0.0.1',             // 數據庫域名 / database host
            'name'=> 'phalapi',               // 數據庫名字 / database name
            'user'=> 'root',                  // 數據庫用戶名 / database user
            'password'=> '',                      // 數據庫密碼 / database password
            'port'=> 3306,                    // 數據庫端口 / database port
            'charset'=> 'UTF8',                  // 數據庫字符集 / database charset
            'pdo_attr_string'=> false,           // 數據庫查詢結果統一使用字符串，true是，false否
            'driver_options'=> array(              // PDO初始化時的連接選項配置
                // 若需要更多配置，請參考官方文檔：https://www.php.net/manual/zh/pdo.constants.php
            ),
        ),
    ),


    // 更多代碼省略……
);

最后，需要給runtime目錄添加寫入權限。

運行和使用

調用接口

在PhalApi，你可以通過service參數（短名字是s參數）指定需要調用的接口服務。例如，訪問默認接口服務。

http://dev.phalapi.net/?s=App.Site.Index

接口請求后結果輸出類似如下：

{
    "ret": 200,
    "data": {
        "title": "Hello PhalApi",
        "version": "2.4.2",
        "time": 1501079142
    },
    "msg": ""
}

對應執行的PHP代碼在./src/app/Api/Site.php文件，源碼片段如下：

<?php
namespace App\Api;
use PhalApi\Api;


/**
 * 默認接口服務類
 * @author: dogstar <chanzonghuang@gmail.com> 2014-10-04
 */
class Site extends Api {
    public function getRules() {
        return array(
            'index'=> array(
                'username'=> array('name'=> 'username', 'default'=> 'PhalApi', 'desc'=> '用戶名'),
            ),
        );
    }


    /**
     * 默認接口服務
     * @desc 默認接口服務，當未指定接口服務時執行此接口服務
     * @return string title 標題
     * @return string content 內容
     * @return string version 版本，格式：X.X.X
     * @return int time 當前時間戳
     * @exception 400 非法請求，參數傳遞錯誤
     */
    public function index() {
        return array(
            'title'=> 'Hello ' . $this->username,
            'version'=> PHALAPI_VERSION,
            'time'=> $_SERVER['REQUEST_TIME'],
        );
    }
}

運行效果，截圖如下：

自動生成的接口文檔詳情頁局部截圖如下：

翻譯

修改./public/init.php文件，可設置當前語言。

// 翻譯語言包設定-簡體中文
\PhalApi\SL('zh_cn');


// Setting language to English
\PhalApi\SL('en');

一張圖告訴你如何使用PhalApi 2.x

PhalApi開發文檔

專為PHPer準備的優雅而詳細的開發文檔，基本都能在文檔找到你要的答案，請看：PhalApi 2.x 開發文檔，http://docs.phalapi.net/#/v2.0/。

文檔使用markdown編寫，文檔頁面截圖如下：

開發文檔大綱：

PhalApi 2.x 開發文檔


    前言
        前言
        如何升級PhalApi？


    一、快速開發
        1.1下載與安裝
        1.2 運行Hello World
        1.3 如何請求接口服務
        1.4 接口響應與在線調試
        1.5 Api接口層
        1.6 DataApi通用數據接口
        1.7 Domain領域層與ADM模式
        1.8 Model數據層與數據庫操作
        1.9 DataModel數據基類
        1.10 單元測試
        1.11 自動加載和PSR-4
        1.12 接口文檔
        1.13 初始化


    二、數據庫
        2.1 數據庫連接
        2.2 數據庫與NotORM
        2.3 數據庫使用和查詢
        2.4 數據庫分庫分表策略
        2.5 連接多個數據庫
        2.6 打印和保存SQL語句
        2.7 定制你的Model基類


    三、高級專題
        3.1 接口參數
        3.2 配置
        3.3 日志
        3.4 緩存
        3.5 過濾器(接口簽名)
        3.6 COOKIE
        3.7 加密
        3.8 國際化
        3.9 CURL請求
        3.10 工具和雜項
        3.11 DI服務匯總
        3.12 擴展類庫
        3.13 SDK包的使用
        3.14 腳本命令
        3.15 MQ隊列
        3.16 錯誤處理

2020視頻教程

B站首發，第一課~第十一課，配套有每節課的視頻知識點大綱。

http://docs.phalapi.net/#/v2.0/video_1

視頻課程：

    PhalApi 2020視頻教程
        第一課 B站首發，2020視頻教程開講啦！
        第二課 視頻教程 - 下載和安裝
        第三課 視頻教程 - Hello World
        第四課 視頻教程 - 如何請求接口服務
        第五課 視頻教程 - 接口響應與在線調試
        第六課 視頻教程 - Api接口層
        第七課 視頻教程 - Domain領域業務層與ADM模式解說
        第八課 視頻教程 - Model數據層與數據庫連接
        第九課 視頻教程 - 測試驅動開發與PHPUnit
        第十課 視頻教程 - 自動加載和PSR-4
        第十一課 視頻教程 - 接口文檔
        視頻教程 - 十分鐘體驗PhalApi Pro，讓PHP接口開發更有趣！
        視頻教程 - 茶店應用實戰

子項目

如果對PhalApi開源框架的內部實現、源代碼和技術架構感興趣，可以查看以下子項目。

phalapi/kernal框架內核
phalapi/notorm數據庫包

PhalApi 2.x 版本的系統架構如下：

PhalApi composer 擴展

phalapi/authAuth權限擴展
phalapi/cliCLI擴展類庫
phalapi/fast-routeFastRoute快速路由
phalapi-aliyun-ossPhalApi-OSS阿里云OSS包
phalapi/PHPMailer基于PHPMailer的郵件發送
phalapi/qiniu七牛云存儲接口調用
phalapi/qrcodePhalApi 二維碼擴展
phalapi/pinyinPhalApi 2.x 拼音擴展
phalapi/jwt基于PhalApi2的JWT拓展
chenall/phalapi-weixin微信擴展
phalapi/wechatmini微信小程序擴展
phalapi/ding-com-bot釘釘企業內部webhook機器人擴展
phalapi-pay支持微信支付和支付寶支付

溫馨提示：以上擴展需要先通過composer安裝再使用。更多擴展類庫的使用和開發，請參考文檔：PhalApi框架擴展類庫：http://docs.phalapi.net/#/v2.0/library。

PhalApi應用插件

運營平臺插件
應用用戶插件
加密解密插件
支付寶插件
茶店微信小程序應用
在線接口文檔主題包

溫馨提示：應用插件和composer擴展的區別在于，應用插件顆粒度更大，功能更具體，可能不僅有數據庫、接口、界面、還可能配合其他終端，并且不受composer的規范約束，是PhalApi自主發明和設計的開發方式。更多請參考：第三方應用插件開發教程：http://docs.phalapi.net/#/v2.0/how-to-dev-plugin。

基于PhalApi開發的技術產品

以下產品均使用了PhalApi開源框架，并為官方自主研發的產品，歡迎個人/團隊/企業使用。

接口大師-即刻搭建您的接口開放平臺(原名：PhalApi專業版)

產品官網：http://pro.phalapi.net/

果創云-后端低代碼開發平臺

產品官網：http://yesapi.cn/

YesDev協作云-在線協作你的全部項目

產品官網：https://www.yesdev.cn/

PhalApi 2.x 版本完美詮釋

2.x 版本系統架構

主要分為三層：

phalapi/phalapi 項目應用層，可使用phalapi/phalapi搭建微服務、接口系統、RESTful、WebServices等。
擴展類庫 擴展類庫是指可選的、可重用的組件或類庫，可以直接集成使用，由廣大開發人員維護分享，對應原來的PhalApi-Library項目。
核心框架 分別兩大部分，PhalApi核心部分kernal，以及優化后的notorm。

其中，各自的composer和github項目分別是：

項目	composer	github
phalapi/phalapi	phalapi/phalapi	phalapi/phalapi
擴展類庫	由廣大開發人員共同維護、分享，composer建議統一注冊到phalapi。	由廣大開發人員共同維護、分享，源代碼可維護在開發者各自的Github倉庫。
核心框架	phalapi/kernal	phalapi/kernal

框架核心部分UML靜態結構圖

PhalApi 2.x 版本的核心框架部分的UML靜態結構圖，高清版如下所示：

首先，綠色部分的PhalApi\PhalApi類是整個接口系統的訪問入口，也就是項目應用系統、客戶端使用的關鍵所在。相關的調用代碼，可以參考統一入口文件的實現代碼片段。

$pai=new \PhalApi\PhalApi();
$pai->response()->output();

只需要兩行代碼，便可完成對接口服務的請求響應。

其次，是黃色部分的Api、Domain和Model這三層，也就是我們常說的ADM分層架構。這部分，需要開發人員關注，因為這也是具體項目開發需要自己實現的部分。

最后，是紅色部分的DI依賴注入，也是整個框架的核心所在。不僅在核心框架中使用頻率最高，乃至在項目應用中也會經常被用到。

核心執行流程時序圖

PhalApi 2.x 版本的核心執行流程時序圖，與1.x 版本基本一致，可以看出，不管技術如何升級，PhalApi的最初的核心時序流程仍保持著活力。唯一變化的是各個類名。

代碼倉庫

Gitee碼云 - PhalApi開源接口框架（1.7k Star）

代碼鏈接：https://gitee.com/dogstar/PhalApi

Github - PhalApi開源接口框架（1.4 Star）

代碼鏈接：https://github.com/phalapi/phalapi

版本更新

2021年7月發布更新了 PhalApi 2.17.2 版本。

PhalApi 2.17.2 版本

[BUG修復]

1、SQL記錄，只提取部分必要的參數，避免全部記錄，以及避免記錄密碼等敏感信息到日志文件

2、翻譯和DataApi參數說明補充

3、DataModel調用不存在方法時的異常提示信息，去掉多余的美元符號

4、在線接口文檔模板判斷調整，避免出現warning

更多歷史版本更新日記，請查看：

http://docs.phalapi.net/#/v2.0/changelog

近在各種網站、論壇逛了幾圈，收集了不少實用的api，為大家提供一點點幫助。。。

一.天氣類api

1.天氣api：

www.tianqiapi.com

(1)實況天氣(基本天氣信息、濕度、能見度、氣壓、空氣質量指數等)

最快3小時更新一次

(2)七日天氣(基本天氣信息、氣象預警、濕度、能見度、氣壓、日出日落、每日小時預報、6大生活指數等)

最快三小時更新一次

(3)全國天氣降水量預報圖(未來24，48，70小時預報圖片url地址)

每兩小時更新一次

專業版可獲取信息更詳細，具體內容查看api文檔，下同

2.和風api:

?dev.heweather.com

(1)常規天氣數據(未來三天日夜天氣狀況，日最高(低)氣溫，日(月)出(落)時間，風速，風力，風向，降水概率，降水量，大氣壓強，能見度，紫外線強度)

(2)空氣質量數據(查詢地區內監測站的名稱、位置和ID，空氣污染指數，各種污染物(PM10,PM2.5,NO2,SO2,CO,O3)的數值)

3.心知天氣：

docs.seniverse.com

(1)天氣實況(天氣狀況，氣溫)

(2)逐日天氣預報(未來三日內，日最高(低)氣溫，風速，風力，風向，降水率)

4.彩云api：

wiki.swarma.net

好像更新了。。。具體內容查看api文檔

5.免費天氣查詢：

?www.sojson.com

6.丫丫天氣：

www.yytianqi.com

7.天行數據天氣接口：

www.tianapi.com

天行數據其他api接口：

www.tianapi.com

這個大概是用過最好的api網站，白嫖狀態下贈送次數最多，按次計費也不算太貴

二.聊天機器人

1.海知智能：

1. docs.ruyi.ai

不光能聊天，還可以在網站里內置技能，實現(翻譯，成語接龍等)數十項功能

2.天行機器人：

www.tianapi.com

白嫖用戶綁定微信后有40000次永久額度，之后1元10000次

3.思知機器人：

www.ownthink.com

4.青云客智能機器人：

api.qingyunke.com

5.圖靈機器人：

?www.turingapi.com

圖靈的官網如果不充值好像每日請求次數很低很低，但好在可以通過其他api網站進行調取www.tianapi.com

6.小i機器人：

模版展示頁面?nlp.xiaoi.com

但小i機器人沒有api使用文檔，想要使用就只能自己分析

import urllib.request

import re

message=“”

msg=urllib.parse.quote(message)

link=urllib.request.urlopen("http://nlp.xiaoi.com/robot/webrobot&callback=__webrobot_processMsg&data=%7B%22sessionId%22%3A%22ff725c236e5245a3ac825b2dd88a7501%22%2C%22robotId%22%3A%22webbot%22%2C%22userId%22%3A%227cd29df3450745fbbdcf1a462e6c58e6%22%2C%22body%22%3A%7B%22content%22%3A%22"+msg+"%22%7D%2C%22type%22%3A%22txt%22%7D")

html_doc=link.read().decode()

reply=re.findall(r'\"content\":\"(.+?)\r\n\"', html_doc)

print(reply)

可以通過這段python代碼進行輸入并取得輸出

三.垃圾分類

垃圾分類的api好像不是太多，就推薦一個好用的吧

www.tianapi.com

四.新聞推送

1.百度新聞：

python 代碼：

import re

url="http://news.baidu.com/"

header={'User-Agent':'UserAgent:Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0)'}

req=urllib.request.Request(url,headers=header)

res=urllib.request.urlopen(req)

html=res.read().decode("utf-8")

pat='<a href=" " .*? target="_blank">(.*?)</a >'

data=re.findall(pat,html)

for v in data:

if "#" not in v[1]:

print(v[1]+":"+v[0])

2.NBA新聞：

www.tianapi.com

好像因為疫情緣故，員工還沒開始上班，網站數據還是春節前的，等疫情過了再說

新聞類的接口還有很多，可以在各種api網站上查詢，就不一一列舉了

五.快遞

1.快遞鳥api：

www.kdniao.com

但是調取這個api需要接口鑒權，對與我們小白好像不太友好……所以：

2.天行api

www.tianapi.com

但天行的這個api有點小貴，注冊只送50額度，之后1元100次，酌情選用

六.人臉識別

1.Face++

人臉檢測 - Face++人工智能開放平臺?www.faceplusplus.com.cn

主要功能：

1.對圖片進行人臉檢測和分析(Detect)

2.比對兩張圖片中的人臉是否為同一人(Compare)

3.在圖片中尋找與目標人臉最相似的一張或多張人臉(Search)

4.對圖片進行美顏(美白，磨皮)，美型(大眼，瘦臉，小臉，去眉毛等)，增加濾鏡等(Beautify)

5.皮膚分析(膚質，單雙眼皮，有無眼袋、黑眼圈、抬頭紋、青春痘、黑頭、法令紋等)

6還可以對車牌，證件等進行識別，具體見api文檔

?console.faceplusplus.com.cn

2.天行數據

相比于Face++想要簡潔一些，只進行簡單的識別，不需要太過復雜的功能，可以選用此api

www.tianapi.com

七.翻譯

1.有道詞典：

?fanyi.youdao.com

2.金山詞霸：

http://open.iciba.com/?c=api?open.iciba.com

3.百度翻譯：

?api.fanyi.baidu.com

八.社交

1.微博：

open.weibo.com

附一個github上比較成熟的項目：

https://github.com/dataabc/weiboSpider?github.com

2.b站：

blog.csdn.net里面都可以找到：

(1)b站實時在線人數與最新投稿

(2)視頻彈幕

(3)評論區留言

(4)視頻下載：盡管github上有這類項目，但要么有的分段下載，有的視頻音頻分開下，有點麻煩…所以還是推薦一個you-get的python庫吧。。。

You-Get 使用方法www.jianshu.com不光能下b站視頻還支持數十個國內外主流視頻網站，但實測好像有些不行，具體可以自己嘗試

3.沙雕app：https://shadiao.app/

這個沒有現成的api可以調用，但可以去網站找客服郵箱，它會要求你給出標識符以及域名或者ip地址，然后給你可以調用的api。主要功能有：

(1)彩虹屁生成器

(2)罵人寶典/撕逼生成器

(3)朋友圈文案生成器

(4)毒雞湯生成器

強調一點：這玩意罵人是真的狠，非常不適宜用于朋友之間開玩笑，建議有切實需要再進行使用！！

九.圖床

由于api大多采取的post，get傳輸方式都無法直接傳輸圖片，只能傳送url地址，而有時需要傳輸的是剛拍出來的本地圖片，還沒有url。盡管可以手動傳送上網來獲取url，但無法自動操作，很麻煩(我自己就被這個東西困擾了好久…)最后采用的sm.ms圖床解決

官網：https://sm.ms/

api文檔：https://doc.sm.ms/

python代碼

head={'Authorization':'OJ9QijpjOLz0DtL8Yxr3ZDOCzHgpMBQl'}

files={'smfile':open(msg['FileName'],'rb')} reply=requests.post('https://sm.ms/api/v2/upload',headers=head,files=files,verify=False)

reply=json.loads(reply.text)

if reply['success']==False:

reply=reply['images']

else:

reply=reply['data']['url']

url=reply

print(url)

sm.ms圖床提供了5個G的空間，感覺還是挺足夠的，實在不行，還可以去刪。

十.武漢新型冠狀病毒疫情信息接口(COVID-19)

疫情來勢洶洶，人們對疫情充滿了關切。盡管能通過各種各樣的渠道獲得疫情播報，從微信小程序、支付寶上獲得各種數據，但如題要制作一個app的話，好像還是調用api方便點。。。

疫情數據：https://www.tianapi.com/apiview/170

疫情播報：https://www.tianapi.com/apiview/169

同程查詢：https://www.tianapi.com/apiview/172

周邊疫情：https://www.tianapi.com/apiview/173

謠言鑒別：https://www.tianapi.com/apiview/171

再放一個大佬利用這幾個接口制作的疫情信息軟件

原貼地址：https://www.52pojie.cn/thread-1096810-1-1.html

百度云鏈接：https://pan.baidu.com/s/1ZtsXAa7zWNtFrqM88R94cg提取碼：tavr

藍奏云鏈接：

https://www.lanzous.com/b0ddqluuj提取碼：8888

十一.藍奏云

順手安利一下上邊那個跟百度網盤不一樣的網盤…

https://www.lanzou.com?

優點：免費使用，空間存儲無限制，下載無限制，不用下載客戶端，上傳下載都不限速，分享文件地址永久有效

缺點：無限空間但單個文件只能上傳100M

最后幾點tips：

1.推薦的最多的還是天行數據api，也可能是因為自己用的比較多。注冊地址：

www.tianapi.com

2.上述api大多不需要接口鑒權，較為適合小白使用，只需注冊得要api_key就可以調用。還有其他大廠的api網站如騰訊AI開放平臺，百度AI開放平臺等需要接口鑒權，也有很多不錯的api可供免費調用。

3.最后也是最關鍵的一條：不需要接口鑒權大大降低了api調用門檻，調用api時應仔細閱讀開放文檔，了解接口更新頻率和時間，及時做好緩存，減小api提供方帶寬消耗所帶來的超額運營支出成本。

以后有時間再詳細更…

在線咨詢

上一篇：WP主題開發14：怎樣添加wordpress主題tr
下一篇：畢業季賣花，手把手教你做一個HTML5鮮花商城

您的項目需求

*請認真填寫需求信息，我們會在24小時內與您取得聯系。

整合營銷服務商

Web服務開發：Spring集成Swagger，3步

halApi開源接口框架

在線示例

快速安裝

composer一鍵安裝

手動下載安裝

部署

數據庫配置

運行和使用

調用接口

翻譯

一張圖告訴你如何使用PhalApi 2.x

PhalApi開發文檔

2020視頻教程

相關書籍

子項目

PhalApi composer 擴展

PhalApi應用插件

基于PhalApi開發的技術產品

PhalApi 2.x 版本完美詮釋

代碼倉庫

版本更新

您的項目需求