Swagger2 在线接口文档及文档下载

Swagger介绍

前后端分离是目前一种非常流行的开发模式，前端和后端开发人员通过接口进行数据交换，因此接口文档显得尤为重要，借助swagger在线接口文档，可以方便查看接口相关信息及进行接口测试，极大地提高了开发效率。swagger是API文档自动生成工具，用于生成、描述、调用和可视化Restful风格的web服务。

• springboot项目如何集成swagger

1、pom文件中添加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.9.2</version>

</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.9.2</version>

</dependency>

2、创建配置类SwaggerConfig

@Configuration

@EnableSwagger2

public class Swagger2Config {

@Bean

public Docket createApi(){

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

//是否开启 (默认开启， false关闭，生产环境建议关闭)

//.enable(false)

.select()

//扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api

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

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo(){

return new ApiInfoBuilder()

//设置文档标题(API名称)

.title("测试API")

//文档描述

.description("测试API说明")

//版本号

.version("1.0")

.build();

}

}

3、编写controller，添加注解

@RestController

@RequestMapping("user")

@Api(tags="用户管理")

public class UserController {

@Autowired

private UserService userService;

@GetMapping("users")

@ApiOperation("用户列表")

public Result<List<User>> user() {

List<User> users = userService.findAll();

return Result.success(users);

}

@GetMapping("{id}")

@ApiOperation("根据id查询")

public Result<User> user(@PathVariable Long id) {

User user = userService.findById(id);

return Result.success(user);

}

...

4、在线访问测试： http://ip:port/swagger-ui.html

5、接口测试及返回结果

• swagger 注解说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义"

@ApiOperation：用在请求的方法上
    value="说明方法的作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，
指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

• 使用Knife4j导出文档

Swagger 接口导出成 Word 格式如何实现？需要使用一个 Swagger 的增强工具Knife4j。

1、添加依赖

<dependency>

<groupId>com.github.xiaoymin</groupId>

<artifactId>knife4j-spring-boot-starter</artifactId>

<version>2.0.9</version>

</dependency>

2、在线访问地址 http://ip:port/doc.html

Knife4j 提供了 4 种格式的离线文档下载：Markdown、Html、Word、OpenAPI 等方式，如图：

Knife4j 还可以实现过滤某一类型的接口、接口搜索、设置公共的请求参数等。