swagger2是基于我们在开发前后端分离项目的时候方便后端开发接口的人员做测试,以及团队之间更好的配合。好处我不多说,我在这主要讲怎么运用swagger2。
1.项目准备
/*
Navicat Premium Data Transfer
Source Server : localhost_3306
Source Server Type : MySQL
Source Server Version : 80026
Source Host : localhost:3306
Source Schema : newsmanagersystem
Target Server Type : MySQL
Target Server Version : 80026
File Encoding : 65001
Date: 20/01/2022 00:05:35
*/
SET NAMES utf8mb4;
SET FOREIGN_KEY_CHECKS = 0;
-- ----------------------------
-- Table structure for topic
-- ----------------------------
DROP TABLE IF EXISTS `topic`;
CREATE TABLE `topic` (
`tid` int NOT NULL AUTO_INCREMENT,
`tname` varchar(50) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
PRIMARY KEY (`tid`) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 36 CHARACTER SET = utf8 COLLATE = utf8_unicode_ci ROW_FORMAT = Dynamic;
-- ----------------------------
-- Records of topic
-- ----------------------------
INSERT INTO `topic` VALUES (1, '国内');
INSERT INTO `topic` VALUES (2, '国际');
INSERT INTO `topic` VALUES (3, '军事录屏修改');
INSERT INTO `topic` VALUES (4, '体育');
INSERT INTO `topic` VALUES (5, '娱乐');
INSERT INTO `topic` VALUES (6, '社会');
INSERT INTO `topic` VALUES (7, '财经');
INSERT INTO `topic` VALUES (8, '科技');
INSERT INTO `topic` VALUES (9, '健康');
INSERT INTO `topic` VALUES (10, '汽车');
INSERT INTO `topic` VALUES (12, '房产');
INSERT INTO `topic` VALUES (13, '家居');
INSERT INTO `topic` VALUES (14, '旅游');
INSERT INTO `topic` VALUES (15, '文化');
INSERT INTO `topic` VALUES (28, '探索');
INSERT INTO `topic` VALUES (29, '另类');
INSERT INTO `topic` VALUES (31, '测试');
INSERT INTO `topic` VALUES (33, '更新测试');
INSERT INTO `topic` VALUES (34, '录屏测试');
SET FOREIGN_KEY_CHECKS = 1;
/*
Navicat Premium Data Transfer
Source Server : localhost_3306
Source Server Type : MySQL
Source Server Version : 80026
Source Host : localhost:3306
Source Schema : newsmanagersystem
Target Server Type : MySQL
Target Server Version : 80026
File Encoding : 65001
Date: 20/01/2022 00:05:42
*/
SET NAMES utf8mb4;
SET FOREIGN_KEY_CHECKS = 0;
-- ----------------------------
-- Table structure for news_users
-- ----------------------------
DROP TABLE IF EXISTS `news_users`;
CREATE TABLE `news_users` (
`uid` int NOT NULL AUTO_INCREMENT,
`uname` varchar(20) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
`u_pwd` varchar(20) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL,
PRIMARY KEY (`uid`) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 8 CHARACTER SET = utf8 COLLATE = utf8_unicode_ci ROW_FORMAT = Dynamic;
-- ----------------------------
-- Records of news_users
-- ----------------------------
INSERT INTO `news_users` VALUES (1, 'admin', 'admin');
INSERT INTO `news_users` VALUES (2, '王八', '123456');
INSERT INTO `news_users` VALUES (3, '小白', '12345678');
INSERT INTO `news_users` VALUES (4, '哈哈哈', '123456');
INSERT INTO `news_users` VALUES (6, 'WYT', '123456');
INSERT INTO `news_users` VALUES (7, 'DFP', '123456');
SET FOREIGN_KEY_CHECKS = 1;
准备好我们要的2个数据表
2.引入swagger2的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
3.使用
这是我们基本的目录结构
2个控制类
一个是控制操作用户的请求地址
一个是控制操作类型的请求地址后面我们会用到
在config包下放sw2的配置
package com.example.springbootdata.config;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2配置信息
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket UsersApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(UsetApiInfo())
.select()
//只显示api路径下的页面
.paths(Predicates.and(PathSelectors.regex("/User/.*")))
.build();
}
@Bean
public Docket TopicApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(TopicApiInfo())
.select()
//只显示api路径下的页面
.paths(Predicates.and(PathSelectors.regex("/Topic/.*")))
.build();
}
private ApiInfo UsetApiInfo(){
return new ApiInfoBuilder()
.title("Users测试文档")
.description("本文档描述了测试接口定义")
.version("1.0")
.contact(new Contact("new DFO", "http://33221@qq.com", "33221@qq.com"))
.build();
}
private ApiInfo TopicApiInfo(){
return new ApiInfoBuilder()
.title("topic测试文档")
.description("本文档描述了测试接口定义")
.version("1.0")
.contact(new Contact("new DFO", "http://33221@qq.com", "33221@qq.com"))
.build();
}
}
注意要添加的2个注解
前2个方法相当于创建2个管理桌面
后2个方法是向2个桌面输入内容。
.paths(Predicates.and(PathSelectors.regex("/Topic/.*")))
是指定该页面下管理是Topic下的所有地址
详细代码我在后面会分享这里讲一些关键的地方
我们给controller的方法添加注释方便阅读文档
同样也在类头为整个类添加注释@API
主要的介绍在这里你们可以去测试一下我在这就测试比较常用的3个
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
4.测试
运行项目在浏览器下输入请求我的端口是8080
http://localhost:8080/swagger-ui.html输入这个就可打开页面了
先点击第一步
这个就是我们刚刚在sw2配置中设置的2个桌面管理 不同的接口
点击第二步
会显示我们controller的请求地址点开具体一个测试
返回的结果
有的时候分局传入的数据格式不同sw2会提示你怎么输入数据