SpringBoot整合Swagger2

SpringBoot整合Swagger2

大家在开发过程中肯定被各种文档占用了很多时间，像阿里的大牛在阿里吐槽大会上也吐槽过被产品经理要求编写的各种文档，PPT占用大量时间。而随着前后端分离和微服务项目架构的流行，在开发过程中对接口文档的质量要求越来越高，或者上下游没有做好及时，有效的沟通，从而导致开发过程困难重重，所以一份好的接口文档直接影响了我们开发人员的工作效率。而Swagger就是这样的一款API框架，它通过后台的配置自动生成接口文档，省去了我们开发完接口还要编写接口文档的繁琐。

准备工作

引入jar包

这里有一个注意点，只有java1.8及以上才能引用swagger2

		<!-- swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
		</dependency>
		<!-- swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.8.0</version>
		</dependency>

配置swaggerAPI基本信息

package com.skill.admin.configuration;

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.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 SwaggerConfiguration {

    @Bean
    public Docket createRestApi(){
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo()) //添加swaggerApi详情信息
               .pathMapping("/")
               .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
               .select()
//               .apis(RequestHandlerSelectors.basePackage("com.skill.admin.system.controller")) //添加过滤条件,默认全扫描
               .paths(PathSelectors.any()) //里是控制哪些路径的api会被显示出来
               .build();
    }


    private ApiInfo apiInfo(){
        Contact contact = new Contact("Alice", "blog.csdn.net", "*****.@email.com");
        return new ApiInfoBuilder().title("SpringBoot整合Swagger") //标题
                .description("SpringBoot整合Swagger，详细信息......") //描述
                .version("1.0") //版本
                .contact(contact) //维护人信息
                .license("Apach 2.0") //许可证
                .licenseUrl("The Apache License") //许可证url
                .build();
    }
}

这个时候我们的swagger就配置好了，输入项目地址 + swagger-ui.html（http://localhost:7070/swagger-ui.html）就能看到我们的swagger界面了

接下来就是创建接口了

swagger注解使用

@Controller
@Api(tags = "用户管理")
@RequestMapping("/system/sysUser")
public class SysUserController {

    @Autowired
    private ISysUserService sysUserService;

    /**
     * @Title:        save
     * @Description:  //用户管理保存
     * @param:        [sysUser]
     * @return:       com.skill.common.utils.HttpResult
     * @author        Alice
     * @date          2021/4/16 10:17
     */
    @ResponseBody
    @PostMapping("/save")
    @ApiOperation("保存用户信息")
    public HttpResult save(@RequestBody SysUser sysUser){
        return HttpResult.success(sysUserService.insert(sysUser));
    }
}

如果参数是一个对象（例如上文的保存接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

@Data
@ApiModel
public class SysUser implements Serializable {

    private static final Long serialVersionUID = 1L;

    @ApiModelProperty(value = "用户id")
    private Long id;
    
    @ApiModelProperty(value = "用户名")
    private String name;
    
    @ApiModelProperty(value = "用户密码")
    private String password;
    
    @ApiModelProperty(value = "加密盐")
    private String salt;
    
    @ApiModelProperty(value = "手机号码")
    private String mobile;
    
    @ApiModelProperty(value = "状态")
    private Integer status;
    
    @ApiModelProperty(value = "邮箱")
    private String email;
    
    @ApiModelProperty(value = "是否管理员")
    private Integer isAdmin;
    
    private Date createTime;
    private String createBy;
    private Date lastUpdateTime;
    private String lastUpdateBy;
}

如果参数不是一个对象，我们可以使用下面这种方式

	@ResponseBody
    @GetMapping("/insert")
    @ApiOperation("保存用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户名", defaultValue = "张三"),
            @ApiImplicitParam(name = "mobile", value = "手机号码", defaultValue = "132****8976", required = true)
    })
    public HttpResult insert(@RequestParam String name, @RequestParam(required = true) String mobile){
        SysUser sysUser = new SysUser();
        sysUser.setName(name);
        sysUser.setMobile(mobile);
        return HttpResult.success(sysUserService.insert(sysUser));
    }

配置完接口后我们的swagger页面就是这样的：

关于swagger的注解本文就不多介绍了，swagger的注解并不多，使用也不复杂，大家可以参考swagger注解详解