Swagger配置与使用
问题:前后端分离时代的到来
前端需要测试后端数据
后端提供接口,实时更新接口的改动
一、Swagger简介
号称世界上最流行的api框架
Restful api文档在线自动生成工具-->api文档与api定义同步更新
直接运行,可以在线测试api接口
支持多种语言(java、php)
在项目中使用swagger需要springfox jar包
- swagger2
- swagger ui
二、springboot集成swagger
新建springboot项目
导入jar包
<!--swaggerjar包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
编写一个helloworld
package com.kj.controller; import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController; @RestController
public class SwaggerController { @RequestMapping("/hello")
public String hello(){
return "hello";
}
}
配置swagger
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig { }
启动类加上
@EnableSwagger2
注解(遇到Unable to infer base url.
bug时加入,可以解决)package com.kj; import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication { public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
} }
启动运行
访问localhost/swagger-ui.html。没有配置port的是这个地址localhost:8080/swagger-ui.html
swagger-ui.html所在文件
三、配置swagger
1、配置ApiInfo
swagger需要一个docket实例
可以看到docket的构造函数,需要一个DocumentationType
public Docket(DocumentationType documentationType) {
this.apiInfo = ApiInfo.DEFAULT;
this.groupName = "default";
this.enabled = true;
this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
this.applyDefaultResponseMessages = true;
this.host = "";
this.pathMapping = Optional.absent();
this.apiSelector = ApiSelector.DEFAULT;
this.enableUrlTemplating = false;
this.vendorExtensions = Lists.newArrayList();
this.documentationType = documentationType;
}
而DocumentationType有三个默认的值
public class DocumentationType extends SimplePluginMetadata {
public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
......
}
所以我们可以这样向容器中创建一个docket
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
此时改配置信息,调用docket的函数即可。
比如修改swagger的api信息,我们需要更改ApiInfo
相关源码
public Docket(DocumentationType documentationType) {
this.apiInfo = ApiInfo.DEFAULT; //api描述
this.groupName = "default";
this.enabled = true;
this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
this.applyDefaultResponseMessages = true;
this.host = "";
this.pathMapping = Optional.absent();
this.apiSelector = ApiSelector.DEFAULT;
this.enableUrlTemplating = false;
this.vendorExtensions = Lists.newArrayList();
this.documentationType = documentationType;
}
//默认的apiInfo
static {
DEFAULT = new ApiInfo("Api Documentation",
"Api Documentation",
"1.0", "urn:tos",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
//作者信息
public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
这时候为我们自己的docket注入咱们自己的apiInfo
即可
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo());
}
private static ApiInfo getApiInfo(){
return new ApiInfo("KJ Api文件",
"swagger测试",
"1.0",
"https://blog.csdn.net/KJ_Study",
new Contact("KJ", "https://blog.csdn.net/KJ_Study", "qi1638629056@163.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
结果如下(其实这个基本没任何效率上的作用)
2、配置扫描接口
有一个方法Docket.select()
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.select()
.build();
}
只能build两个方法apis与paths
配置扫描目标
有扫描全部any
,一个都不扫描none
,基于包扫描basePackage
,通过方法注解扫描(扫描有这个注解的方法,可以自己加入GetMapper.class的参数),通过类注解扫描
用的多的还是basePackage
我们指定一个扫描包
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
.build();
}
结果
3、过滤路径
扫描带有/kj/ url的api,我们只有一个/hello请求,所以不会有任何api
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kj.controller"))
.paths(PathSelectors.ant("/kj/**"))
.build();
}
4、配置是否启用swagger
将docket的enabled属性改为false即可
//docket的部分源码
public Docket(DocumentationType documentationType) {
this.apiInfo = ApiInfo.DEFAULT;
this.groupName = "default";
this.enabled = true; //是否使用swagger
this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
this.applyDefaultResponseMessages = true;
this.host = "";
this.pathMapping = Optional.absent();
this.apiSelector = ApiSelector.DEFAULT;
this.enableUrlTemplating = false;
this.vendorExtensions = Lists.newArrayList();
this.documentationType = documentationType;
}
public Docket enable(boolean externallyConfiguredFlag) {
this.enabled = externallyConfiguredFlag;
return this;
}
所以我们enable一下
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
.build()
.enable(false);
}
实际使用:我们通过外部的环境来判断是否调用swagger
@Bean
public Docket docket(Environment environment){
//设置显示要调用swagger的环境,可以有多个值
Profiles profiles = Profiles.of("dev");
//判断当前的环境与指定的是否一样
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
.build()
.enable(flag);
}
我们有多个配置文件,一个用于开发,一个用于部署
5、配置api文档的分组
主要的是groupName
public Docket(DocumentationType documentationType) {
this.apiInfo = ApiInfo.DEFAULT;
this.groupName = "default";
this.enabled = true;
this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
this.applyDefaultResponseMessages = true;
this.host = "";
this.pathMapping = Optional.absent();
this.apiSelector = ApiSelector.DEFAULT;
this.enableUrlTemplating = false;
this.vendorExtensions = Lists.newArrayList();
this.documentationType = documentationType;
}
@Bean
public Docket docket(Environment environment){
Profiles profiles = Profiles.of("dev");
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kj.controller"))
.build()
.enable(flag)
.groupName("KJ");
}
我们可以看到一个docket一个分组。要想要多个我们再创建几个docket即可。
注意组名不能相同,如果相同spring会报bug并结束进程
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.groupName("A");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.groupName("B");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
.groupName("C");
}
不同后端开发人员选择自己的组,就可以只看到自己的api
6、实体类配置
只要返回值中存在,就会被swagger扫描
编写一个pojo
package com.kj.pojo;
public class User {
private String username;
private String password;
}
编写一个方法
@RestController
public class SwaggerController {
@RequestMapping("/hello")
public String hello(){
return "hello";
}
@PostMapping("/user")
public User user(){
return new User();
}
}
我们也可以在实体类加上注注释(在显示时,只显示注解配置的内容),显不显示与这个注解无关
package com.kj.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
private String password;
}
可以看到私有方法是看不到的
同样我们也可以给方法加注释,或者给参数加注释
@RestController
public class SwaggerController {
@ApiOperation("哈喽方法")
@RequestMapping("/hello")
public String hello(){
return "hello";
}
@PostMapping("/user")
public User user(){
return new User();
}
@GetMapping("/hello2")
public String hello2(@ApiParam("用户名") String name){
return "hello";
}
}
四、发送请求
下面就可以看到结果了
Swagger配置与使用的更多相关文章
- 一、Swagger配置
一.Swagger配置 1.注解不显示 SwaggerConfig文件下 //c.IncludeXmlComments(GetXmlCommentsPath()): 内下面添加: c.Inclu ...
- Spring Boot项目简单上手+swagger配置+项目发布(可能是史上最详细的)
Spring Boot项目简单上手+swagger配置 1.项目实践 项目结构图 项目整体分为四部分:1.source code 2.sql-mapper 3.application.properti ...
- swagger配置
1.pom.xml <!--swagger2--> <dependency> <groupId>io.springfox</groupId> <a ...
- swagger 配置- ssm
swagger 配置 - ssm swagger 是一个用来看接口的工具,具体效果如下,这里用的是swagger2 1.porm.xml <dependency> <groupId& ...
- 尝试从零开始构建我的商城 (二) :使用JWT保护我们的信息安全,完善Swagger配置
前言 GitHub地址 https://github.com/yingpanwang/MyShop/tree/dev_jwt 此文对应分支 dev_jwt 此文目的 上一篇文章中,我们使用Abp vN ...
- webapi Swagger 配置 services.BuildServiceProvider() 报警 ASP0000 问题处理
问题起源 网上的常见配置 Swagger 配置 在Startup类的 ConfigureServices 使用 services.BuildServiceProvider() ,其中有段代码如下: v ...
- 《Asp.Net Core3 + Vue3入坑教程》-Net Core项目搭建与Swagger配置步骤
简介 <Asp.Net Core3 + Vue3入坑教程> 此教程仅适合新手入门或者前后端分离尝试者.可以根据图文一步一步进操作编码也可以选择直接查看源码.每一篇文章都有对应的源码 教程后 ...
- SpringBoot初探之Swagger配置
Swagger是一个用于描述和测试restful接口的工具,只要在定义restful接口时增加一些类和方法的描述注解,通过很简单的配置就可以得到一个展示接口定义页面,也可以在页面上设置参数提交测试接口 ...
- swagger配置和简单使用
说明:本地环境idea + maven3.5 + springboot2.0.0 + springfox-swagger2 2.8.0 + springfox-swagger-ui 2.8.0 + ...
- .net core web api swagger 配置笔记
参考网址: --配置步骤见如下链接https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swa ...
随机推荐
- 优酷kux转mp4
利用YouKu客户端下载的视频格式为kux,只能通过YouKu客户端播放,很不方便.在网上看到有人通过ffmpeg解码器进行转换,写成了批处理,如下: @echo off setlocal enabl ...
- 刷题[GWCTF 2019]你的名字
解题思路 打开发现需要输入名字,猜测会有sql注入漏洞,测试一下发现单引号被过滤了,再fuzs下看看过滤了哪些 长度为1518和1519的都有过滤,测试一下,感觉不是sql注入了.那还有什么呢,考虑了 ...
- python环境变量的安装与配置
安装最新的3.x(2.x如今已经不常见) 下图来源:百度(电脑已安装,不能重复) 一定要勾选"Add Python 3.6 to PATH".(如果没有勾选在安装完成后需要手动添加 ...
- P4395 [BOI2003]Gem 气垫车
树形dp 首先,我们可以考虑dp,把这个问题看成一个树的染色问题,用dp[i][j]表示以i为根节点,将树染成第i种颜色的最小代价,那么我们可以得到j的最大值是(log(maxn)/log(2)+1) ...
- Java程序运行内存机制
Java程序运行内存机制 栈内存包留调用方法.变量的区域,堆内存是new对象的区域,方法区为保存class文件的区域. 程序刚开始时,先加载类文件相应的数据到方法区,然后就从main()方法开始执行. ...
- Centos-分割文件-split
split 分割文件,将一个文件分割为多个 相关选项 -b 指定文件大小,可以在size后面添加单位后缀,b表示512字节,k表示1KB,m表示MB -n 指定分割文件的长度,默认为1000行 -d ...
- Python练习题 011:成绩打分
[Python练习题 011] 利用条件运算符的嵌套来完成此题:学习成绩>=90分的同学用A表示,60-89分之间的用B表示,60分以下的用C表示. ---------------------- ...
- 使用SSM框架实现图片的上传
SSM实现图片上传功能 效果 在前端页面点击上传图片功能按钮,即弹出文件管理器,选择图片并上传: 思路 在前端页面添加 input 标签,type选择file. 在后端controller编写方法. ...
- P2590 树的统计
一道树剖的模板题 首先,由于本人比较懒,就把单点修改写成了区间修改,其实也没有有多大区别(关键是我不会写单点修改QAQ) 不得不说,树剖的码量比较大,调了一上午才勉强调完. 这道题要求我们支持 单点修 ...
- JavaScript利用函数反转数组
要求: 给定一数组,将其元素倒序排列并输出. 代码实现: // 利用函数翻转任意数组 reverse 翻转 function reverse(arr) { var newArr = []; for ( ...