Springboot集成Swagger自动生成接口文档

为什么使用Swagger来自动生成接口文档

Swagger是一个完整的框架，项目上用于自动化生成对应的接口文档并且可以在可视化工具上直接进行接口测试，我会在接下来给大家整理一下Swagger2.0+ 版本 跟 Swagger3.0版本的区别和部署方式

1.项目集成Swagger

下面会用两种方式分别是Maven跟Gradle来集成Swagger，当然前提是你必须有了一个Springboot脚手架，此次的Swagger集成都是基于Sprongboot

1.1 Maven集成Swagger

pom文件中的 代码片.

       <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

1.2 Gradle集成Swagger

Gradle文件中的 代码片.

    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'

2.开始配置Swagger

当通过上述的两种方式导入了所需要的jar包之后，我们就可以开始来配置Swagger了，首先我们先配置一个SwaggerConfig类来开启Swagger

1.创建一个SwaggerConfig.java

SwaggerConfig.java 中的 代码片.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.CacheControl;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * @description: Swagger2配置
 * @date: 2020-11-19 12:25  
 **/
//表示是一个配置类
@Configuration 
//开启Swagger
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
	//因为Swagger是通过侵入代码的方式来达到自动生成文档的所以这里可以设置一个开关用来在
	//生产环境上关闭 swagger.enabled=false即可关闭
    @Value("${swagger.enabled:false}")
    private boolean swaggerabled;
    @Value("${swagger.api.info.title}")
    private String title;
    @Value("${swagger.api.info.description}")
    private String description;
    @Value("${swagger.api.info.version}")
    private String version;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) //swagger版本如果导入的swagger依赖是3.0的那么这里的Type就是.OAS_30
                .enable(swaggerabled)
                .apiInfo(getApiInfo()).groupName("XXX-api")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.XXX.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
        		//Api文档的标题
                .title(title)
                //Api文档的描述
                .description(description)
                //Api文档的版本号
                .version(version)
                .termsOfServiceUrl("")
                .build();
    }
}

3.处理入参的实体类User

User文件中的 代码片.

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.hibernate.validator.constraints.Length;
import javax.validation.constraints.NotEmpty;
import java.util.Date;

/**
 * @description:
 * @author: 
 * @date: 
 **/
@Data
@ApiModel( description= "请求的用户实体类")
public class User {
    protected String id;
    /** 用户编号 [32,0] Not NULL */
	@ApiModelProperty(hidden = true)
    protected String department;
   }

在实体类中加入 @ApiModel 注解即可 desription是对实体的描述
可以用看到在属性中我们使用到了 @ApiModelProperty 注解并且属性 hidden=true 这样我们在自动生成的接口文档中的请求体中就看不到该属性了

这样我们就完成了配置Swagger的第一步，接下来我们对需要自动生成接口文档的Controller进行处理

4.处理Controller

Controller中的 代码片.

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * @description:
 * @author: 
 **/
@RestController
@Api(tags = "Swagger测试")
@RequestMapping("/test")
public class UserController {
	
	@Autowired
	private UserService userService; //用户service 里面用一些数据获取的处理 

    @ApiOperation(value = "获取用户实体类",notes = "根据ID获取用户实体类")
    @ApiImplicitParam(name = "user",value = "用户实体类",dataType = "",required = true)
    @PostMapping("/getUserById")
    public User getUserById(@RequestBody User user)
    {
        return userService.getUserById(user);
    }
}

如上对Controller进行添加@Api注解表示一个模块可以理解成一个接口文档@Api中的方法这里就不介绍了

在UserController中的getUserById方法上我们可以看到有Swagger的一些注解跟自动生成的接口文档的一些对应关系

5.修改Springboot启动类

在Springboot启动类的Application中我们需要加入Swagger的注解

Application文件中的 代码片.

@SpringBootApplication
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

6.访问通过注解自动生成的SwaggerUi

上面在 Applicaiton 中加入了 @EnableSwagger2 的注解之后，我们启动Spriingboot项目记得先添加Springboot-web依赖让他成为一个web项目，启动之后我们访问地址
http://localhost:8080/swagger-ui.html 即可这里我是在本地启动而且springboot的server.port是默认的8080
效果如下

7.后续更新第二种界面

后续更新第二种界面展示的自动生成文档的界面