springboot使用swagger2

springboot中使用swagger可以自动生成接口说明文档，是我们开发api接口的利器，下面说一下springboot快速集成swagger的步骤。
一、快速集成
1、maven的pom.xml加入依赖

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

2、增加swagger2配置文件

mport org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxxxxx.tsp.rps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("TSP订单资源接口Api")
                .description("TSP订单资源接口Api")
                .termsOfServiceUrl("")
                .contact("devteam")
                .version("1.0")
                .build();
    }

}

大部分情况下，访问项目地址，后面加"/swagger-ui.html"就会出现如下界面：

二、可能出现的问题
1、出现 no mapping的情况，需要增加一个 WebMvcConfigurerConfig，代码如下：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;

@Configuration
public class WebMvcConfigurerConfig extends WebMvcConfigurerAdapter  {


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

    }
}

2、需要访问权限的情况，如果你的项目均需要token验证，则需要在springboot的配置文件增加以下内容：

security.ignored=/swagger-ui.html,/swagger-ui.html/*,/webjars/**,/error,/swagger-resources/**

三、注解规范
1、【必填】@Api(value = “”, tags = “”)
此注解应用在类上面，表示对类的说明。其中，
（1）tags=“说明该类的作用，可以在UI界面上看到的注解” （非空时将覆盖value的值）
（2）value=“说明类的作用”

@Api(value="影城配置",tags={"影城后台配置"})

2、【必填】@ApiOperation(notes = “”, value = “”)
此注解作用在方法上面，说明该方法的用途等
（1）value=“说明该方法的作用和用途”
（2）notes=“对该方法的备注信息说明”

@ApiOperation(value="修改影城退改签配置",notes="输入参数为影城退改签配置的json")

3、【非必填】@ApiImplicitParams
此注解作用在类上，表明对一组参数的说明
@ApiImplicitParam 用在@ApiImplicitParams注解的内部，表明对一组参数的各个方面进行具体的说明
（1）name参数名
（2）value对参数的说明
（3）required参数是否必传（值为true或者false）
（4）dataType参数类型，默认是String，其他例如：Integer
（5）paramType 参数放在什么地方
· header --> 请求参数的获取：@RequestHeader ·
query --> 请求参数的获取：@RequestParam ·
path（用于restful接口）–> 请求参数的获取：@PathVariable ·
body（不常用） ·
form（不常用）

  @ApiImplicitParams({
        @ApiImplicitParam(name = "configs", value = "影院退改签规则", required = true, paramType = "body", dataType = "List")
})

4、【非必填】@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse用在@ApiResponses中，常用于表示一组错误的信息的响应
（1）code错误代码
（2）massege错误信息提示
（3）response 抛出异常的类
示例：

@ApiResponses({ 
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
        })

5、【非必填】@ApiParam用在请求方法中，描述参数的信息
name参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value参数的简要说明。
defaultValue参数默认值
required 属性是否必填，默认为false [路径参数必须填]
示例：

@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "name", value = "用户名", required = false) @RequestParam(value = "name", required = false) String account,
                @ApiParam(name = "pass", value = "密码", required = false) @RequestParam(value = "pass", required = false) String password){}

6、【非必填】@ApiIgnore用在类或者方法上，表明在swagger2中忽略这个类或者方法或者参数

public void updateRefundFee(@RequestBody List<CinemaRefundAlterFeeRule> configs, @ApiIgnore UserProfile userProfile) {
        cinemaService.updateRefundFee(configs,userProfile.getName());
    }

四、生成环境禁用swagger
在配置文件中，增加profile的限制。