Swagger的简单应用

注意事项
1.本篇文章主要记录的是SpringMVC集成Swagger
2.集成的是Swagger2,有兴趣的可以去研究Swagger,注意两个版本的引入的jar和配置方式不同
3.Swagger2引入的jar包版本和其它的一些jar包可能冲突，运行失败，请选择正确的版本
配置步骤
1.引入jar包,我选择的是2.6.1

         <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!--springfox-ui的jar包(里面包含了swagger的界面静态文件)-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

2.配置文件

@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages = {"接口路径"})
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                /***
                        重要的两个方法:
                        apis():指定要生成文档的接口包基本路径
                        paths():指定针对哪些请求生成接口文档
                 ****/
                //.apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("接口路径"))
                 .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX项目接口文档")
                .description("XXX API接口文档")
                .version("版本号")
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build();
    }

3.springmvc-servlet.xml配置文件

 <!-- 启用注解 -->
    <context:annotation-config />
    <!--将静态资源交由默认的servlet处理 -->
    <mvc:default-servlet-handler />
    <!--重要！配置swagger资源不被拦截 -->
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
    <!--重要！将你的SwaggerConfig配置类注入 -->
    <bean id="swaggerConfig" class="" />

4.web.xml文件配置

  <servlet-mapping>
    <servlet-name>springMVC</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

5.一些注解的简单用户
Swagger2 基本使用：

@Api 描述类/接口的主要用途

//在类的头部定义
@Api("保存订单信息相关接口") 
@Controller

@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的参数
@ApiImplicitParams 描述方法的参数(Multi-Params)

//如果有多个参数，需要用@ApiImplicitParams，单个参数可以直接使用@ApiImplicitParam
@ApiOperation("保存订单信息接口")
    @ApiImplicitParams({
    @ApiImplicitParam(name = "userId", value = "用户ID", dataType = "int"),
    @ApiImplicitParam(name = "", value = "", dataType = "int"),
    @ApiImplicitParam(name = "", value = "", dataType = "String")})

@ApiIgnore 忽略某类/方法/参数的文档

如果某个类或者某个方法不是被外部调用可以直接使用这个注解忽略掉

6.区分环境！！一定要注意生产环境不要暴露接口的东西，不然被访问到就惨了，内网就无所谓了~

public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.comratings.brandqapi.controller"))
                 .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .enable(true); //定义为true可以被看到，flase不可以看到
    }

7.关键的一步，校验配置的是否成功
端口后面有系统名则需要加上
http://localhost:8080/项目名称/swagger-ui.html