Swagger入门
本文参考: https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/
Spring Boot 框架是目前非常流行的微服务框架,我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了展示如何在 Spring Boot 项目中使用 Swagger,主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。
一,Swagger简介
Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分:
- Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们 OpenAPI 规范。
- Swagger UI:它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档,后文我将使用浏览器来查看并且操作我们的 Rest API。
- Swagger Codegen:它可以通过为 OpenAPI(以前称为 Swagger)规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
二,使用Swagger
2.1 添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.0</version>
</dependency>
2.2 创建配置类
package com.lmc.config;
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;
/**
* @Author lmc
* @Description
* @Date: Create in 22:05 2020/8/24
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 配置扫描接口
* @return
*/
@Bean
public Docket createRestApi() {
//设置要显示的swagger环境
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置Swagger信息
.select()
//RequestHandlerSelectors配置要扫描接口的方式
//RequestHandlerSelectors.basePackage指定要扫描的包
//any()扫描全部
//none()全部不扫描
//withMethodAnnotation:扫描方法上的注解
//withClassAnnotation:扫描类上的注解
.apis(RequestHandlerSelectors.basePackage("com.lmc.controller"))
//paths 过滤什么路径
.paths(PathSelectors.any())
.build();
}
/**
* 配置swagger信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Lmc TEST")
.description("Lmc TEST Restful API")
.contact(new Contact("lmc", "", "limincong@163.com"))
.termsOfServiceUrl("http://localhost:6000/")
.version("1.0")
.build();
}
}
2.3 创建测试接口
package com.lmc.controller;
import com.lmc.beans.User;
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.RestController;
/**
* @Author lmc
* @Description
* @Date: Create in 22:11 2020/8/25
*/
@RestController
public class TestController {
@GetMapping("/test")
public String test() {
return "test ...";
}
@GetMapping("/hello")
public String hello() {
return "hello ...";
}
}
访问 http://localhost:8080/swagger-ui.html
2.3 接口注释
2.3.1 创建实体类
package com.lmc.beans;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @Author lmc
* @Description
* @Date: Create in 22:59 2020/8/25
*/
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
}
2.3.2 测试接口
@PostMapping("/user")
//ApiOperation接口,描述接口的
@ApiOperation("Hello控制类")
public User user(@ApiParam("用户名") String username){
return new User();
}
访问 http://localhost:8080/swagger-ui.html ,/user 接口出现注释。
未完待续…