SpringBoot之Swagger2文档生成

SpringBoot之Swagger2文档生成

1、Swagger2介绍

编写和维护接口文档是每个程序员的职责，前面我们已经写好的接口现在需要提供一份文档，这样才能方便调用者使用。考虑到编写接口文档是一个非常枯燥的工作，我们采用Swagger2这套自动化文档工具来生成文档，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。 

2、SpringBoot开启Swagger2支持

第一步：在pom.xml中加入Swagger2的依赖

<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>

第二步：创建Swagger2配置类

package com.offcn.config;

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 {

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("Spring Boot中使用Swagger2构建RESTful APIs")

                .description("优就业")

                .termsOfServiceUrl("http://www.ujiuye.com/")

                .contact("Sunny")

                .version("1.0")

                .build();

    }

}

3、修改Controller增加文档注释

通过@ApiOperation注解来给API增加说明 通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明

/**

 * 更新指定id用户信息

 * @param id

 * @param user

 * @return

 */

@PutMapping("/{id}")

@ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")

@ApiImplicitParams({

         @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),

         @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")

     })

public String updateUser(@PathVariable("id") Long id,User user) {

user.setId(id);

userRepository.saveAndFlush(user);

return "success";

}

/***

 * 删除指定id用户

 * @param id

 * @return

 */

@DeleteMapping("/{id}")

@ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")

    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")

public String deleteUser(@PathVariable("id") Long id) {

userRepository.deleteById(id);

return "success";

}

4、查看Swagger2文档

重启应用访问地址：http://localhost:8080/swagger-ui.html 

点开每个接口，可以查看接口详情