spring boot基于swagger生成接口文档

swagger 3.0版本尝鲜

使用步骤

• pom文件引入依赖

  	<dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-boot-starter</artifactId>
          <version>3.0.0</version>
      </dependency>
  

• springboot启动类增加注解@EnableOpenApi
  
• 启动应用访问swagger文档地址：http://localhost:8080/swagger-ui/index.html
• 如果需要定制化文档则需要引入config配置文件

  @Configuration
  public class Swagger3Configuration {
  
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.OAS_30)
                  .select()
                  .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                  .paths(PathSelectors.any())
                  .build().apiInfo(new ApiInfoBuilder()
                          .title("swagger test")
                          .description("test swagger 接口文档")
                          .version("1.0.0")
                          .build());
      }
  }
  

使用总结

• 相对2.x版本减少了config配置，使用起来更加快捷方便
• spring-boot的2.0.4.RELEASE版本使用时会报如下图所示的错误，【解决方法】：升级spring-boot的版本，我直接升级到了2.2.8.RELEASE版本，然后就可以正常是用来
  
• 启动后始终会显示Basic Error Controller，目前还没有屏蔽该接口的方法，增加config配置文件之后该接口自动屏蔽了
  

项目地址点这里

说明：项目已经升级到swagger3.0版本了，如果需要使用swagger2.x版本的可以参考下面的步骤进行配置

一、构建spring-boot项目简单介绍

自己没有项目可以测试时，先在本地搭建一个spring-boot项目去验证swagger生成API说明文档的流程，构建spring-boot项目有三种方式，可以参考官方文档：https://spring.io/guides/gs/spring-boot/#use-maven
我这里使用的是maven构建方式，需要导入的包有：

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.5.RELEASE</version>
    </parent>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
    <properties>
        <java.version>1.8</java.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

然后编写部分代码，确保项目可以正常启动。项目构建就说这么一点吧，后面开始介绍如何使用swagger生成API文档。

二、使用swagger生成API文档

1、导入maven依赖

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

2、在项目目录下编写SwaggerConfig类

package com.test.swagger;

import com.google.common.base.Predicate;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
@ComponentScan(basePackages = {"com.test.swagger.controller"})
@SpringBootApplication
public class SwaggerConfig {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerConfig.class, args);
    }
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(paths())
                .build()
                .useDefaultResponseMessages(false);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("《--Swagger生成API文档演示案例--》")//标题
                .termsOfServiceUrl("")
                .description("演示API文档生成的过程")//描述
                .version("1.0.0")//版本号
                .build();
    }

    //可以匹配满足下面条件的任何一个表达式
    private Predicate<String> paths() {
        return or(
                regex("/api/.*"),
                regex("/some.*"),
                regex("/contacts.*"),
                regex("/pet.*"),
                regex("/springsRestController.*"),
                regex("/test.*"));
    }
}

3、TestController代码

package com.test.swagger.controller;
import com.test.swagger.bean.TestRequest;
import com.test.swagger.bean.TestResult;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/test")
@Api(value = "TestController", description = " Test api", tags = "Test控制器")
public class TestController {

    @ApiOperation(value = "测试POST请求", notes = "测试方法")
    @RequestMapping(value = "/postAsBody", method = RequestMethod.POST)
    public TestResult testPostAsBody(@RequestBody TestRequest testRequest) {
        TestResult result = new TestResult();
        result.setParam1(testRequest.getParam1());
        result.setParam2(testRequest.getParam2());
        return result;
    }

    @ApiOperation(value = "测试POST请求(form)", notes = "测试方法")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "param1", value = "第一个参数", required = true, paramType = "form"),
            @ApiImplicitParam(name = "param2", value = "第二个参数", required = true, paramType = "form"),
    })
    @RequestMapping(value = "/postAsForm", method = RequestMethod.POST)
    public TestResult testPostAsForm(String param1,String param2) {
        TestResult result = new TestResult();
        result.setParam1(param1);
        result.setParam2(param2);
        return result;
    }

    @ApiOperation(value = "测试GET请求", notes = "测试方法")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public String testGet() {
        return "**测试**";
    }
}

4、本地访问

项目启动后访问 http://localhost:8080/swagger-ui.html#/ 就可以查看简单的API文档了

先研究这么多，更多Swagger的相关注解说明，直接参考官方文档：
Springfox Reference Documentation