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 版本完美诠释

代码仓库

版本更新

您的项目需求