spring boot集成Swagger2

第一步：jar包的引入

这里我的springboot 和framework都是1.5.9

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

 

第二步：swagger的配置启动类

有人说这个类必须放到启动类同级，无稽之谈，扫描包的配置基础去补补。

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.WebMvcConfigurerAdapter;
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;

/**
 * 自动文档注解
 * 访问地址：注意端口后面+上context-path
 * springboot中的swagger：http://localhost:8080/swagger-ui.html
 * druid数据库监控　：http://localhost:8080/druid/index.html
 */
@Configuration
public class SwaggerConfig extends WebMvcConfigurerAdapter {

   @Bean
   public Docket businessDocket() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 为当前包路径
            .apis(RequestHandlerSelectors
             .basePackage("com.sanyi.qibaobusiness.core.controller.busniess"))
            .paths(PathSelectors.any())
            .build();
   }

   // 构建 api文档的详细信息函数
   private ApiInfo apiInfo() {
      return new ApiInfoBuilder() // 页面标题
            .title("三易业务端绘图端 API")
            .termsOfServiceUrl("http://localhost:8080/swagger-ui.html")
            .contact("lanhaifeng") // 创建人
            .version("1.0") // 版本号           
            .description("访问 http://localhost:8080/swagger-ui.html")//描述
            .build();
   }

   /**
    * 我们在访问http://localhost/swagger-ui.html时，这个swagger-ui.html相关的所有前端静态文件都在springfox-swagger-ui-2.2.2.jar里面。
    * SpringBoot自动配置本身并不会把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。我们加上这个映射即可
    * 这个也是发生404的解决方案
    * @param registry
    */
   @Override
   public void addResourceHandlers(ResourceHandlerRegistry registry) {
      registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
      registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   }

}

 

三、在启动类加上@EnableSwagger2注解。

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.ServletComponentScan;
import org.springframework.boot.web.support.SpringBootServletInitializer;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@EnableSwagger2
@SpringBootApplication
//@EnableConfigurationProperties({YmlConfig.class})//不需要了.因为YmlConfig类上有@Component注解
@MapperScan("com.sanyi.qibaobusiness.core.mapper") //配置扫描mapper接口的地址
public class QibaobusinessApplication extends SpringBootServletInitializer {


   public static void main(String[] args) {
      SpringApplication.run(QibaobusinessApplication.class, args);
   }

   @Override
   protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
      return application.sources(QibaobusinessApplication.class);
   }
}

四、在controller中添加注解

这些注解看实际使用情况自行添加。

@Api：用在类上，说明该类的作用
 
@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了。
 
@ApiImplicitParams：用在方法上包含一组参数说明
 
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面。
 
@ApiResponses：用于表示一组响应
 
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
 
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
@ApiModelProperty： 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，
对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在model中的顺序。

 

下面罗列下实际开发中最常用的三种写法，注意请求方法必须写。这三种基本够用了。httpMethod这个参数必须设置。

//注解在类上,其实只有这个value值有效
@Api(value="/decorate[装修选型版块Controller]", tags="装修选型版块Controller")

//注解在方法上,注意这个httpMethod必须要写，不然各种请求都会帮你罗列出来
//paramType = "path"这个参数，如果不是请求方法后面直接带参数可以去掉，例如/getUserId/2,这种请求这个参数就需要配置，否则应该去除
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",httpMethod = "GET")//如果没有请求参数，用这个一个就行
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")

//多个请求参数，注意这里就没有 paramType = "path"。
@ApiOperation(value="合作方式", notes="选择合作方式",httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "machinePrcie", value = "购买机械价格", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "daystate", value = "按天计算折扣", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "overserPrice", value = "按天计算价格", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "areastate", value = "按面积计算折扣", required = true, dataType = "Double"),
            @ApiImplicitParam(name = "prcie", value = "按面积计算总价", required = true, dataType = "Double")
    })

 

四、安全验证放过swagger相关

实际上线则不能放过，或者相关文档删除，相关接口必须对外保密。

/*swagger*/
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");

 

五、访问：http://localhost:8080/swagger-ui.html

当出现：fetching resource list: http://localhost:8080/v2/api-docs 时稍微等待一两分钟，之后文档会自动加载出来