springboot api文档_Spring Boot学习：如何使用Swagger构建自己的API文档-CSDN博客

本文链接：https://blog.csdn.net/weixin_42212792/article/details/113318746

Swagger

随着前后端分离架构和微服务架构的流行，我们使用Spring Boot来构建RESTful API项目的场景越来越多，在多人协作的团队中，前后端的沟通成本往往比较大。在这样的背景下，Swagger出现了(当然还有其他的就不一一例举了)。

使用 Swagger 集成文档具有以下几个优势：

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务

开始整合Swagger2

在上一篇的项目基础上，我们来使用一下Swagger。

首先，我们需要在pom.xml中添加依赖,如下:


<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>

接下来我们来编写一个SwaggerConfig配置类
新建一个包:com.zhlab.demo.config,创建SwaggerConfig类
SwaggerConfig.java

package com.zhlab.demo.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;

/**
 * @ClassName SwaggerConfig
 * @Description //SwaggerConfig配置类
 * @Author singleZhang
 * @Email 405780096@qq.com
 * @Date 2020/10/17 0017 上午 11:11
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {


@Bean
public Docket creatRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(this.apiInfo())
.select()
//扫描指定路径
.apis(RequestHandlerSelectors.basePackage("com.zhlab.demo.controller"))
// 扫描所有有注解的api，用这种方式更灵活
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描所有
// .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("zhLab Demo Api Doc")
.description("api document of zhLab Demo")
.version("1.0.1")
.build();
}

}

※说明:

在类上，添加 @EnableSwagger2 注解，标记项目启用 Swagger API 接口文档。
通过 createRestApi() 方法，创建 Swagger Docket Bean
更多的配置可以在Docket.java、ApiInfo.java两个类的源码中查看

修改上一篇中的HelloController控制器

package com.zhlab.demo.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * @ClassName HelloController
 * @Description //第一个Springboot接口
 * @Author singleZhang
 * @Email 405780096@qq.com
 * @Date 2020/10/16 0016 上午 10:55
 **/
@RestController
@RequestMapping("/system/user")
public class HelloController {

/* 方法注解 */
@ApiOperation(value = "方法名:打招呼", notes = "打招呼方法的测试")
@GetMapping("/hello")
public String sayHello(/* 参数注解 */ @ApiParam(value = "参数:名字" , required=true ) @RequestParam String name){
return "hi"+name+" ,I can say hello";
}
}

启动项目,在浏览器输入http://localhost:8080/swagger-ui.html显示下图:

swagger-ui

执行一下，测试一下接口:

常用注解说明

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。
@Api: 修饰整个类，用于controller类上
@ApiOperation: 描述一个接口，用户controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时，描述对象的字段
@ApiResponse: Http响应其中的描述，在ApiResonse中
@ApiResponses: Http响应所有的描述，用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误的返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParam: 多个请求参数