spring boot集成swagger构建API文档

使用swagger不用手工写API相关的word文档了，并且还可以使用swagger生成的API文档进行测试，使用起来倍儿爽。接下来咱们就来搞一个demo案例。

先是pom.xml引用和版本： 

<modelVersion>4.0.0</modelVersion>	
  <parent>	
    <groupId>org.springframework.boot</groupId>	
    <artifactId>spring-boot-starter-parent</artifactId>	
    <version>1.5.8.RELEASE</version>	
    <relativePath/> <!-- lookup parent from repository -->	
  </parent>	
  <groupId>com.lawt</groupId>	
  <artifactId>swagger-demo</artifactId>	
  <version>0.0.1-SNAPSHOT</version>	
  <name>swagger-demo</name>	
  <description>Demo project for Spring Boot</description>	

	
  <properties>	
    <java.version>1.8</java.version>	
  </properties>	

	
  <dependencies>	
    <dependency>	
      <groupId>org.springframework.boot</groupId>	
      <artifactId>spring-boot-starter-web</artifactId>	
    </dependency>	
    <dependency>	
      <groupId>io.springfox</groupId>	
      <artifactId>springfox-swagger2</artifactId>	
      <version>2.6.1</version>	
    </dependency>	

	
    <dependency>	
      <groupId>io.springfox</groupId>	
      <artifactId>springfox-swagger-ui</artifactId>	
      <version>2.6.1</version>	
    </dependency>	
  </dependencies>

 springboot启动类：

import org.springframework.boot.SpringApplication;	
import org.springframework.boot.autoconfigure.SpringBootApplication;	
@SpringBootApplication	
public class SwaggerDemoApplication {	
  public static void main(String[] args) {	
    SpringApplication.run(SwaggerDemoApplication.class, args);	
  }	
}

swagger相关扫描和配置：

import org.springframework.beans.factory.annotation.Value;	
import 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 SwaggerConfig {	
   //扫描路径	
    private final String SWAGGER_SCAN_BASE_PACKAGE	
     = "com.lawt.swaggerdemo.controller";	
    //开关	
    @Value("${swagger.enable}")	
    private Boolean enable;	
    @Bean	
    public Docket createRestApi() {	
        return new Docket(DocumentationType.SWAGGER_2)	
                .enable(enable)	
                .apiInfo(apiInfo())	
                .select()	
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))	
                .paths(PathSelectors.any())	
                .build();	
    }	
    private ApiInfo apiInfo() {	
        return new ApiInfoBuilder()	
                .title("我的swagger demo API")	
                .version("1.0.0")	
                .build();	
    }	
}

一个controller类：

import com.lawt.swaggerdemo.User;	
import io.swagger.annotations.Api;	
import io.swagger.annotations.ApiImplicitParam;	
import io.swagger.annotations.ApiOperation;	
import org.springframework.web.bind.annotation.GetMapping;	
import org.springframework.web.bind.annotation.PathVariable;	
import org.springframework.web.bind.annotation.RestController;	
@RestController	
@Api(description = "用户信息操作")	
public class UserController {	
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")	
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")	
    @GetMapping("/user/{id}")	
    public User getUserById(@PathVariable("id") Integer id) {	
        return new User(10001, "lawt");	
    }	
}

实体类User:

import io.swagger.annotations.ApiModelProperty;	
public class User {	
    @ApiModelProperty(value = "用户id")	
    private Integer userId;	
    @ApiModelProperty(value = "用户名称")	
    private String userName;	

	
    public User(Integer userId, String userName) {	
        this.userId = userId;	
        this.userName = userName;	
    }	
   //get set method .....	
}

配置项：

server.port=8801	
#如果线上环境不需要swagger功能，需要改成false	
swagger.enable=true

启动，并访问：

http://127.0.0.1:8801/swagger-ui.html

页面显示：

点击 Show/Hide

点击右边的  获取用户详细信息

输入参数 

点Try it out! 

显示 linux环境下怎么请求改接口，请求参数、返回参数等信息。

Ok，自此demo已经搞定，swagger远不止这些功能。

可以参考：

官网： https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview