Swagger使用配置详解

Swagger学习

Swagger项目公司一直在使用，没时间整理下，现在抽空做个记录，方便以后查看。

Swagger是最受欢迎的RestFul api文档生成工具之一。可以直接类上方法上或者字段上进行注释，方便开发者查看。跟随项目启动，可以很好的进行测试。更多Swagger信息大家可以自行百度，下面直接进入正题：

代码奉上–maven依赖

 
        
            io.springfox
            springfox-swagger2
            2.2.2
        
        
            io.springfox
            springfox-swagger-ui
            2.2.2
        

spring整合Swagger(Swagger配置中心)

package com.graduation.design.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/**
 * @author: xieyong
 * @date: 2019/5/5 22:44
 * @Description:
 */
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.blog"))
                .paths(PathSelectors.any())
                .build()
                //.globalOperationParameters(params())
                ;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot2中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注：")
                .termsOfServiceUrl("XXXXXXXXXXXX")
                .contact("陪你度过漫长的岁月")
                .version("1.0")
                .build();
    }

    /**
     * 防止@EnableMvc把默认的静态资源路径覆盖了，手动设置的方式
     *
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

使用

@RestController
@RequestMapping("/v1/device/manager/detail")
@Api(value = "/v1/device/manager/detail", description = "设备管理-设备详情",tags = "设备管理-设备详情接口")
public class ActiveDetailController {
    ∂
@PostMapping("/queryDeviceByActiveById")
    @ApiOperation(value = "根据活动id查询对应绑定设备列表属性", notes = "根据活动id查询对应绑定设备列表属性")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "activeId", value = "活动Id", paramType = "query", required = true, dataType = "Long")
    })
    public Result queryDeviceByActiveById(@RequestParam(value="activeId", required=true)Long activeId) {
        return Result.ofSuccess(null);
    }
}

一些常用的注释：

@Api 注解在controller类上
@ApiModel 注解在类上，一般是实体类
@ApiOperation 注解在方法上，表明方法级解释
@ApiImplicitParams 注解在方法上，一般与@ApiImplicitParam共用，多个参数逗号隔开,表请求参数
@ApiResponses 注解在方法上表响应，一般与@ApiResponse公用