springboot整合swagger-爱代码爱编程
前言
在日常前后端分离开发的过程中,前端和后端需要进行api对接进行交互实现一个完整的功能,就需要一个api规范文档,方便前后端的交互,但api文档不能根据代码的变化发生实时动态的改变,这样后端修改了接口,前端不能及时获取最新的接口,导致调用出错,需要手动维护api文档,加大了开发的工作量和困难,而swagger的出现就是为了解决这一系列的问题。
Swagger的概述
swagger是一套基于OpenAPI规范构建的开源工具,使用RestApi
1、代码变,文档变
2、跨语言,支持多种语言
3、swagger-ui 呈现出来的是一份可交互式的API文档,可以直接在文档页面尝试API的调用
4、可以将文档规范导入相关工具(postman、soapui),这些工具将会为我们自动地创建自动化测试
补充:
RestApi格式是根据请求的方式决定本次请求的一个操作,譬如:get-->读,post-->写(增、删、改),put-->修改,delete-->删除
OpenApi与语言无关,只是一种规范,可以使用yaml和json格式进行编写,这样更利于我们和机器进行阅读
swagger主要包含了以下三个部分:
- swagger editor:基于浏览器的编辑器,我们可以使用它编写我们OpenApi规范(yaml或者json配置)
- Swagger UI:他会将我们编写的OpenApi规范呈现为交互式的API文档,后文我将使用浏览器来查看并且操作我们的RestApi
- Swagger Codegen:它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程
作用
是一个动态生成接口文档的一个框架,用于和前端或测试岗位的同事进行对接。
实现案例
1,在pom.xml里导入依赖配置
<!--导入swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger用来生成前端页面-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2,新建一个config文件夹并新建以下文件
SwaggerConfig.java
package com.xxgc.helloworld.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.w3c.dom.DocumentType;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否开启前端ui显示 生产环境调为false
.enable(true)
.select()
//扫描有哪些接口(controller)要生成文档
.apis(RequestHandlerSelectors.basePackage("com.xxgc.helloworld.controller"))
//接口中所有路径都扫描
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
//api文档标题
.title("HelloWorld工程")
//文档描述
.description("工程文档描述")
//服务条款url
.termsOfServiceUrl("https://www.baidu.com")
//版本号
.version("1.0.0")
.build();
}
}
InterceptorConfig.java
package com.xxgc.helloworld.config;
import com.xxgc.helloworld.interceptor.JWTInterceptors;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import java.util.ArrayList;
/**
* @program: helloword
* @description: 拦截器配置
* @author: liutao
* @create: 2022-03-07 16:11
**/
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
//配置拦截器规则
public void addInterceptors(InterceptorRegistry registry){
//swagger相关
ArrayList<String> swagger = new ArrayList<>();
swagger.add("/*.html");
swagger.add("/swagger-resources/**");
swagger.add("/webjars/**");
swagger.add("/v2/**");
swagger.add("/swagger-ui.html/**");
}
}
3,使用
controller.java
package com.xxgc.helloworld.controller;
import com.xxgc.helloworld.po.Info;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.PropertySource;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
@PropertySource(value = "classpath:system.properties")
@RequestMapping("/info")
@Api(value="hello接口",tags ="用于返回helloworld",description = "测试helloworld")
public class HelloController {
@Value("${system.name}")
private String system;
@ApiOperation(value = "获取helloworld",notes = "获取helloworld")
@GetMapping("/hello")
@ResponseBody
public Info hello(){
return new Info(200,system+"hello world");
}
@ApiOperation(value = "给什么返回什么",notes = "你给什么返回什么")
@GetMapping("/getMsg")
@ResponseBody
public Info getMsg(@ApiParam(name="msg",value="信息",required = true) String msg){
return new Info(-201,msg);
}
}
效果图