简介
Swagger 是什么？
用Swagger能够在后端写好接口后进行测试，测试过程非常方便。
Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。
PS：Swagger 遵循了 OpenAPI 规范，OpenAPI 是 Linux 基金会的一个项目，试图通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程。
Swagger 官网地址：https://swagger.io/
Swagger 有什么用？
从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用：
- 将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档；
- 当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题；
- 通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本。
访问网址
swagger2是：http://localhost:8080/swagger-ui.html
swagger3是：http://localhost:8080/swagger-ui/index.html
常用注解
注意观察：swagger2的注解基本都是以API开头的，以此来判断注解是否为swagger2注解。同样,swagger3也有类似特性。
swagger2 | swagger3 | 注解位置 |
@Api(tags=“接口描述”) | @Api(tags=“接口描述”) | controller类上 |
@ApiOperation(value = “接口方法描述”) | @Operation(summary = “接口方法描述”) | controller 方法上 |
@ApiModelProperty(value = “字段描述”) | @ApiModelProperty(value = “字段描述”) | JavaBean的字段上 |
@ApiModel(“实体类的描述”) | @ApiModel(“实体类的描述”) | JavaBean上 |
@EnableSwagger2 | @EnableOpenApi | 配置类上 |
@ApiImplicitParams | @ApiImplicitParams | controller的方法参数中 |
@ApiImplicitParam | @ApiImplicitParam | @ApiImplicitParams 下的的子参数 |
@ApiParam(name = “参数描述”) | @Parameter(description = “参数描述”) | controller 方法的参数中 |
Swagger2的使用
引入依赖
swagger2必须要引入springfox-swagger2、springfox-swagger-ui这两个依赖
lombok插件要引入lombok依赖
<!--swagger依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>创建配置类
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.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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(webApiInfo())
.select()
.paths(Predicates.not(PathSelectors.regex("/error.*")))
// .apis(RequestHandlerSelectors.basePackage("com.it"))
.build();
}
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
.title("网站-中心API文档")
.description("本文档描述了接口定义")
.version("1.0")
.contact(new Contact("hello", "hello","6666666666@qq.com"))
.build();
}
}这样swagger就配置完成了，接下来是使用方式
使用
在entity实体类上使用
@Data
public class User {
@ApiModelProperty(value = "id")
private String id;
@ApiModelProperty(value = "用户名")
private String userName;
@ApiModelProperty(value = "年龄")
private int age;
}在controller实体类上使用
package com.it.controller;
import com.it.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
@Api(tags = "欢迎来到")
@RestController
@RequestMapping("/hello")
public class swaggerController {
@ApiOperation(value = "写在方法上的1")
@GetMapping("/getTest")
public User get(User user){
return user;
}
@PostMapping("post")
public User post(User user){
return user;
}
@DeleteMapping("delete")
public User delete(User user)
{
return user;
}
@PutMapping ("put")
public User put(User user)
{
return user;
}
}访问地址
http://localhost:8080/swagger-ui.html
图示
输入内容后，点击try it out ，即可得到结果
swagger2使用起来非常方便，引入依赖，创建一个配置类就能直接用了，用postman还得手动创建每个访问链接，非常麻烦，swagger2算是挺方便了。
swagger3
它与swagger2的差异在于
配置文件上添加的注解是@EnableOpenApi而swagger2是@EnableSwagger2 访问地址http://localhost:8080/swagger-ui/index.html 而swagger2是http://localhost:8080/swagger-ui.html pom引入的文件只有一个 springfox-boot-starter 而swagger2有两个springfox-swagger2 springfox-swagger-ui
引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>加入配置类
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
@EnableOpenApi //启用swagger
@Configuration
public class Swagger3Config implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
//.apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) //只有在接口上加了Operation注解才展示
.paths(PathSelectors.any())
.build()
//.globalRequestParameters(getGlobalRequestParameters())
.globalResponses(HttpMethod.GET, getGlobalResonseMessage())
.globalResponses(HttpMethod.POST, getGlobalResonseMessage());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("联系")
.contact(new Contact("牧歌ing", "https://blog.csdn.net/u013010499", "666666@qq.com"))
.version("1.0")
.build();
}
private List<Response> getGlobalResonseMessage() {
List<Response> responseList = new ArrayList<>();
responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
return responseList;
}
}使用
entity实体类
和swagger2对比没有变化
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("用户")
public class User {
@ApiModelProperty(value = "id")
private String id;
@ApiModelProperty(value = "用户名")
private String userName;
@ApiModelProperty(value = "年龄")
private int age;
}controller
import com.it.entity.User;
import io.swagger.annotations.Api;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.*;
@Api(tags="欢迎接口11")
@RestController
@RequestMapping("/hello1")
public class HelloController {
@Operation(summary = "一个Rest") //接口的备注信息
@RequestMapping(value = "request",method = RequestMethod.GET)
public User rest(User user){
return user;
}
@Operation(summary = "一个Get") //接口的备注信息
@GetMapping("get")
public User get(User user){
return user;
}
@PostMapping("post")
public User post(User user){
return user;
}
@DeleteMapping("delete")
public User delete(User user)
{
return user;
}
@PutMapping ("put")
public User put(User user)
{
return user;
}
}appication.properties
# 在测试环境中用到，生产环境需设置为false
springfox.documentation.swagger-ui.enabled=true访问网址：http://localhost:8080/swagger-ui/index.html
可以看到,ui变大变好看了点
本文暂时没有评论，来添加一个吧(●'◡'●)