SpringBoot整合Swagger2实战

说明

本文代码取自实际项目，确保可用。

导入依赖

            <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>

配置文件

创建Swagger的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.litewms.front.controller")) //暴露api的模块，通常是controller
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("lite wms")
                .description("轻量级wms")
                .contact(new Contact("ph", "", ""))
                .version("0.0.1")
                .build();

    }
}

静态资源映射

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

如果你使用了安全框架，需要放行相关路径。

比如这个项目整合了jwt和security

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Autowired
    UserInfoServiceImpl userInfoService;

    @Autowired
    JwtAuthorizationTokenFilter jwtAuthorizationTokenFilter;

    @Autowired
    TokenLoginFilter tokenLoginFilter;

    @Autowired
    JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint;

    @Autowired
    public void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(userInfoService).passwordEncoder(passwordEncoderBean());
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.exceptionHandling()
                .authenticationEntryPoint(jwtAuthenticationEntryPoint)
                .and().csrf().disable()
                .authorizeRequests()
                .antMatchers("/login").permitAll()
                 .antMatchers("/swagger-ui.html").permitAll()
                 .antMatchers("/webjars/**").permitAll()
                 .antMatchers("/swagger-resources/**").permitAll()
                 .antMatchers("/v2/*").permitAll()
                 .antMatchers("/csrf").permitAll()
                .antMatchers(HttpMethod.OPTIONS, "/**").anonymous()
                .anyRequest().authenticated()
                .and()
                .addFilterAt(tokenLoginFilter, UsernamePasswordAuthenticationFilter.class)
                .addFilterAfter(jwtAuthorizationTokenFilter, TokenLoginFilter.class).httpBasic();

    }

    @Bean
    public PasswordEncoder passwordEncoderBean() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    @Override
    protected AuthenticationManager authenticationManager() throws Exception {
        return super.authenticationManager();
    }
}

重点是

.antMatchers("/swagger-ui.html").permitAll()
                 .antMatchers("/webjars/**").permitAll()
                 .antMatchers("/swagger-resources/**").permitAll()
                 .antMatchers("/v2/*").permitAll()
                 .antMatchers("/csrf").permitAll()

常用注解

配置好后，启动项目，访问

http://localhost:8080/swagger-ui.html

controller

controller可以看作是api的分类，一般不需要过多配置，只要写一个中文注释即可。

例如

@Api(tags = "入库申请表")
@RestController
@RequestMapping("/front/inapply")
public class InApplyController {

method

方法对应每一个请求url。

@Api(tags = "入库申请表")
@RestController
@RequestMapping("/front/inapply")
public class InApplyController {
    @Autowired
    private InApplyService inApplyService;

    /**
     * 列表
     */
    @ApiOperation(
            value = "获取用户申请表",
            notes = "备注",
            response = InApply.class,
            httpMethod = "PUT"
    )
    @RequestMapping("/list")
    public R list(){
        return R.ok();
    }

效果：

我们想让前端看到的，无非就是一下几点

1、请求路径

这个已经有了，图中的 /front/inapply/list

这是controller和method路径的聚合，比较直观，框架默认的，无需设置。

2、请求的含义

 @ApiOperation的value来注释，对应于“获取用户申请表”，

notes字比较小，适合放对这个接口的详细说明。

3、请求方法

通过httpMethod指定。

当然，如果你的请求路径是@GetMapping这些，就不用指定了，会自动识别。

但如果是@RequestMapping这种，比较笼统，swagger会生成所有的请求方式(GET POST .......)，这个时候就要显示的指定了。

4、返回体类型

可以通过response显示的指定返回类型。

如果不添加，则是方法的返回类型。

例如上图添加了注解InApply.class，那么文档中会显示出来

如果不指定，则默认为方法的返回值类型，

5、参数

如果需要对参数进行定制

    @ApiImplicitParams({
            @ApiImplicitParam(
                    name = "id",
                    value = "参数说明",
                    required = true,
                    paramType = "/path",
                    dataType = "Integer",
                    example = "12345"
            )
    })

    @ApiResponses(
            {
                    @ApiResponse(code=404, message = "访问资源不存在")
            }
    )
    @RequestMapping("/info/{id}")
    public R<InApply> info(@PathVariable("id") Integer id){

        return R.ok();
    }

效果：

model

这里的model指的是实体类，主要在两个地方用到。

如果不加注解，则文档中给将会没有中文注释

 

通过@ApiModelProperty来给字段加注释：

/**
 * 入库申请总表
 *
 */
@ApiModel(
		value =  "用户申请表",
		description = "用户申请表的详细信息"
)
@Data
@TableName("tb_in_apply")
public class InApply implements Serializable {
	private static final long serialVersionUID = 1L;

	/**
	 * 主键
	 */
	@TableId(type = IdType.AUTO)
	@ApiModelProperty(value = "主键", required = true, dataType = "int")
	private Integer id;
	/**
	 * 业务流水号
	 */
	@ApiModelProperty(value = "流水号")
	private String serialNo;
	/**
	 * 状态
	 */
	@ApiModelProperty(value = "状态")
	private Byte status;
	/**
	 * 创建人
	 */
	@ApiModelProperty(value = "创建人")
	private Integer createBy;
	/**
	 * 更新人
	 */
	@ApiModelProperty(value = "更新人")
	private Integer updateBy;
	/**
	 * 创建时间
	 */
	@ApiModelProperty(value = "创建时间")
	private Date createTime;
	/**
	 * 更新时间
	 */
	@ApiModelProperty(value = "更新时间")
	private Date updateTime;
	/**
	 * 回收站标志
	 */
	@ApiModelProperty(value = "回收站标志")
	private String deleted;

}

效果图：

拓展

全局配置返回码

 

//swagger2的配置文件，在项目的启动类的同级文件建立
@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable",  havingValue = "true")
public class SwaggerConfig {
    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {

        // 配置全局参数返回状态
        java.util.List<ResponseMessage> resMsgList = Arrays.asList(
                new ResponseMessageBuilder().code(200).message("成功！").build(),
                new ResponseMessageBuilder().code(-1).message("未知错误，请联系管理员！").build(),
                new ResponseMessageBuilder().code(10001).message("参数校验错误！").build(),
                new ResponseMessageBuilder().code(10002).message("请求方法错误！").build(),
                new ResponseMessageBuilder().code(10003).message("查询的结果为空！").build(),
                new ResponseMessageBuilder().code(10004).message("对象不能为空！").build(),
                new ResponseMessageBuilder().code(20001).message("用户不存在!").build(),
                new ResponseMessageBuilder().code(20002).message("超级管理员账号无法删除!").build(),
                new ResponseMessageBuilder().code(20003).message("用户已存在!").build(),
                new ResponseMessageBuilder().code(20004).message("登录验证失败，请检查用户名或密码！").build(),
                new ResponseMessageBuilder().code(20005).message("尚未登录！").build());


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("ams.web.ams.controller")).paths(PathSelectors.any())
                .build()
                .globalResponseMessage(RequestMethod.GET, resMsgList)
                .globalResponseMessage(RequestMethod.POST, resMsgList)
                .globalResponseMessage(RequestMethod.PUT, resMsgList)
                .globalResponseMessage(RequestMethod.DELETE, resMsgList);
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("智慧档案管理系统后台API")
                // 创建人信息
                .contact(new Contact("",  "",  "1376034301@qq.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述")
                .build();
    }
}