Swagger在线api文档工具使用

网上看了很多Swagger的介绍demo，但是有一些demo都有点小问题，现在介绍一下下面亲测有效的方法

1、引入依赖jar包

 <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.6.1</version>
</dependency>
<!-- swagger-ui 为项目提供api展示及测试的界面 -->
<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.6.1</version>
</dependency>

2、创建配置文件

@Configuration
@EnableSwagger2
public class ApiConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("大师兄集成swagger的接口测试")
                .description("闻道有先后，术业有专攻。")
                .termsOfServiceUrl("http://blog.csdn.net/qq_27093465?viewmode=contents")
                .contact(new Contact("csdn大师兄", "http://blog.csdn.net/qq_27093465", "cmshome@163.com"))
                .license("")
                .licenseUrl("")
                .version("1.0.0")
                .build();
    }
}

3、接口上配置参数

@ApiOperation(value = "新建统计数据到重庆市级平台数据库", notes = "新建统计数据到重庆市级平台数据库")
    @ApiImplicitParam(name = "data", value = "统计对象数组的字符串", required = true, dataType = "String")
    @RequestMapping(value = "synRecStatInfo", method = RequestMethod.POST)
    @ResponseBody
    public ResultInfo recRecInfo(@RequestParam String data, @RequestParam String senderCode) {
        ResultInfo result = new ResultInfo(true);
        //接口的具体逻辑
        return result;
    }

4、页面接口的api文档展示

页面的api接口的展示url后缀是/swagger-ui.html

5、页面接口展示出错解决

• 输入url显示404报错：可能是因为不支持解析后缀为html的资源文件，需要在web.xml中加上如下配置(看看你本地的资源文件需要哪些后缀就加上，如果嫌麻烦就全部加上)

<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.htm</url-pattern>
    <url-pattern>*.jpg</url-pattern>
    <url-pattern>*.png</url-pattern>
    <url-pattern>*.gif</url-pattern>
    <url-pattern>*.css</url-pattern>
    <url-pattern>*.js</url-pattern>
    <url-pattern>*.swf</url-pattern>
    <url-pattern>*.pdf</url-pattern>
    <url-pattern>*.java</url-pattern>
    <url-pattern>*.class</url-pattern>
    <url-pattern>*.xls</url-pattern>
    <url-pattern>*.xlsx</url-pattern>
    <url-pattern>*.et</url-pattern>
    <url-pattern>*.vm</url-pattern>
    <url-pattern>*.html</url-pattern>
  </servlet-mapping>

• 输入url显示接口样式，但是没有创建接口的相关显示，需要在接口中输入后缀为/v2/api-docs的url查看是否能返回相关的json数据，如果报错，则根据报错的相关信息来修改代码的配置

• 在启动服务的过程中，有可能Spirng的版本和swagger的版本起冲突报错，这个需要自己调整

6、Swagger的参数配置

• @Api
  该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性：

  • tag
    API分组标签。具有相同标签的API将会被归并在一组内展示
  • value
    如果tags没有定义，value将作为Api的tags使用
  • description
    API的详细描述，在1.5.X版本之后不再使用，但实际发现在2.0.0版本中仍然可以使用

• @ApiOperation
  在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

  • value
    对操作的简单说明，长度为120个字母，60个汉字
  • notes
    对操作简要说明
  • httpMethod
    HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
  • code
    默认为200，有效值必须符合HTTP协议中的状态值

• @ApiImplicitParams
  注解ApiImplicitParam的容器类，以数组方式存储。

• @ApiImplicitParam
  对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：

  • name
    参数名称
  • value
    参数的简短叙述
  • required
    参数是否必须
  • dateType
    参数类型
  • paramType
    参数传入的请求类型

==注意==：我在Swagger的2.6版本(高版本的Swagger可以使用默认配置)可以不用在Controller类的方法中写swagger的注解参数，在在线的接口文档中可以使用默认的参数解析