springboot + Swagger
学习目标：
- 了解Swagger的作用和概念
- 了解前后端分离
- 在SpringBoot中集成Swagger
swagger简介
现在开发，很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。
大部分采取的方式：Vue + SpringBoot，Vue通过js渲染页面，后端把数据传递给js，早期前端只负责写页面，然后把写好的HTML页面给后端，后端使用模板引擎（Jsp，Thymeleaf、 freemarker）进行开发。
前后端分离的好处：各自开发，相对独立，松耦合，前后端通过API进行交互，后端提供接口给前端，前端去调用该接口，但可能会导致前后端团队人员不能做到及时协商，出现一些问题。解决方式：早期使用实时更新文档，但非常繁琐，后来又使用postman来进行一些测试。
使用：
-
新建一个springboot+web项目
-
导入依赖
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.3.0.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.ryan</groupId> <artifactId>springboot-08-swagger</artifactId> <version>0.0.1-SNAPSHOT</version> <name>springboot-08-swagger</name> <description>Demo project for Spring Boot</description> <properties> <java.version>11</java.version> </properties> <dependencies> <!--springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!--springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project> -
测试环境：略
-
编写Swagger配置类
package com.ryan.swagger.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.env.Environment; import springfox.documentation.RequestHandler; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; 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; import java.util.ArrayList; @Configuration @EnableSwagger2 public class SwaggerConfig { //swagger有自己的bean实例——Docket //配置了swagger @Bean public Docket docket(){ //假设这里有一个业务，我只希望在生产环境中使用swagger，其他环境不需要 //第一步，配置多个环境，第二步：传一个环境参数（Environment）， //第三步：获取当前环境（environment.acceptsProfiles(profiles)），第四步：判断环境，第五步，传到enable方法中即可 //这里就不多测试了 return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //自定义组名（团队开发中的一组），如果有多个组，就是多个Docket，一个组对应一个Docket .groupName("ryan") .enable(true)//是否开启swagger，如果为false，则swagger不能在浏览器中被访问 //测试题， .select() //配置指定需要扫描的包，除了basePackage还有其他的可以点出来看，例如any none... .apis(RequestHandlerSelectors.basePackage("com.ryan.swagger.controller")) //.paths(PathSelectors.any())//此方法为过滤方法 .build(); } public ApiInfo apiInfo(){ Contact contact = new Contact("ryan", "https://blog.youkuaiyun.com/codebeef", "635726567@qq.com"); return new ApiInfo( "ryan的SwaggerApi文档", "努力努力再努力", "v1.0", "https://blog.youkuaiyun.com/codebeef", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList() ); } }效果：
编写实体类
package com.ryan.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
public User() {
}
public User(String username, String password) {
this.username = username;
this.password = password;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
效果：通过注解给实体类添加api
编写controller
package com.ryan.swagger.controller;
import com.ryan.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(description = "用户管理API")
@RestController
public class HelloController {
@ApiOperation("添加用户")
@PostMapping("/add")
public User add(@ApiParam("用户名") String username, @ApiParam("密码") String password){
return new User();
}
@ApiOperation("修改用户")
@PostMapping("/update")
public String update(@ApiParam("用户名") String username, @ApiParam("密码") String password){
return "修改完成";
}
@ApiOperation("删除用户")
@GetMapping("/delete")
public String delete(@ApiParam("用户编号") Integer id){
return "已删除";
}
@ApiOperation("查询用户")
@RequestMapping("/query")
public User query(){
User user = new User();
user.setUsername("ryan");
user.setPassword("ryan123");
return new User();
}
}
效果：通过注解添加api，注意RequestMapping会把所有方式都显示出来
还可以在上面进行测试
注解总结：
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiModel：用对象来接收参数 ，修饰类
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述，一般描述错误的响应
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParam：单个参数描述
@ApiImplicitParam：一个请求参数，用在方法上
@ApiImplicitParams：多个请求参数
总要的两个依赖
<!--springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
优点总结：
- 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
- 接口文档实时更新
- 可以在线测试
Swagger是一个优秀的工具，几乎所有大公司都有使用他
注意：在正事发布的时候，关闭Swagger，这是出于安全考虑，同时可以减小内存
学习来源：B站up主狂神说，感觉不错，感兴趣的可以去看下
3172
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
