15-SpringBoot-整合Swagger

最新推荐文章于 2025-01-19 22:41:34 发布

Mls_Lucky

最新推荐文章于 2025-01-19 22:41:34 发布

阅读量316

点赞数

分类专栏： SpringBoot 文章标签： springboot

本文链接：https://blog.youkuaiyun.com/qq_45632660/article/details/115328062

版权

SpringBoot 专栏收录该内容

15 篇文章

订阅专栏

文章目录

1、引言
2、什么是Swagger
3、官方提供的工具
4、SpringBoot整合Swagger
5、扩展: Swagger UI页面的皮肤

1、引言

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档和实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用前端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常还会抱怨别人写的代码没有写注释，然而自己写起代码来，最讨厌的也是写注释。所以仅仅只听过强制了来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

2、什么是Swagger

1、是一款让你更好的书写API文档规范且完整的框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

在这里插入图片描述

3、官方提供的工具

在这里插入图片描述

Swagger Codegen：通过Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也能生成多种语言的服务端和客户端代码。支持通过 jar 包、docker、node 等方式在本地化执行生成。也可以在后面的 Swagger Editor 中在线生成。

Swagger UI：提供了一个可视化的 UI 页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署 UI 项目。

Swagger Editor：类似于 Markdown 编辑器的编辑 Swagger 描述文件的编辑器，该编辑器支持实时预览描述文件的更新效果，也提供了在线编辑器和本地部署器俩种方式。

Swagger Inspector：感觉和 Postman 差不多，是一个可以对接口进行测试的在线版的 postman。比如在 Swagger UI 里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Springfox Swagger：Spring 基于 Swagger 规范，可以将基于 SpringMVC 和 Spring Boot 项目的项目代码，自动生成 JSON 格式的描述文件。本身不是属于 Swagger 官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

4、SpringBoot整合Swagger

1、引入依赖

<!-- 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、编写Swagger配置类

即拿即用

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                //扫描哪个接口的包
                .apis(RequestHandlerSelectors.basePackage("com.shule"))
                .build().apiInfo(new ApiInfoBuilder()
                        //接口文档标题
                        .title("标题: SpringBoot 整合 Swagger 使用")
                        //接口文档描述
                        .description("详细信息: SpringBoot 整合 Swagger,详细信息......")
                        // 版本信息
                        .version("1.1")
                        // 开发文档的联系人
                        .contact(new Contact("shule", "http://www.baidu.com","2252950365@qq.com"))
                        //接口的规范
                        .license("This Baidu License")
                        //接口规范的地址
                        .licenseUrl("http://www.baidu.com")
                        .build());

    }
}

3、启动Springboot项目

4、访问Swagger的UI界面

Swagger UI: http://localhost:8080/swagger-ui.html

在这里插入图片描述

5、使用Swagger构建

1、开发Controller接口

@RestController
public class UserController {

    @GetMapping("/findAll")
    public Map<String, Object> findAll() {
        Map<String, Object> map = new HashMap<>();
        map.put("success", "查询所有数据成功");
        map.put("status", true);
        return map;
    }
}

2、重启项目重新访问SwaggerUI界面

在这里插入图片描述

6、Swagger注解

1、@Api

作用:用来指定模块类的描述文字
修饰范围: 修饰整个类，一般用在controller上

@Api(tags = "用户服务")
public class UserController {
}

在这里插入图片描述

2、@ApiOperation

作用: 用来对接口中具体方法做描述
修饰范围: 一般用在controller里面的接口方法上

@GetMapping("/findAll")
//value 接口描述
//notes: 详细描述
@ApiOperation(value = "查询所有用户接口",notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;用来查询所有用户信息的接口")
public Map<String, Object> findAll() {
    Map<String, Object> map = new HashMap<>();
    map.put("success", "查询所有数据成功");
    map.put("status", true);
    return map;
}

在这里插入图片描述

3、@ApiParam

作用: 单个参数描述
修饰范围: 一般用在方法的形参里面

 @DeleteMapping("/deleteId")
@ApiOperation(value = "删除用户",notes = "<font color='red'>描述:</font>根据id删除用户信息")
public void deleteId(@ApiParam("删除用户id") int id){
    //....删除操作
}

在这里插入图片描述

4、@ApiImplicitParams

作用：用来方法中参数进行说明
修饰范围：一般用来描述方法中的形参，如果有多个形参建议使用这个注解

@PostMapping("save")
@ApiOperation(value = "保存用户信息接口",
              notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;用来保存用户信息的接口")
//dataType是形参的类型，如果不定义无论形参定义什么类型，最后都会默认转换为String类型
//defaultValue是默认传递的参数值
//如果使用的是 RestFul/(路径变量) 风格进行传参，必须再添加一个 paramType="path"
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "用户 id", dataType = "String", defaultValue = "21"),
    @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", defaultValue = "AK47")
})
public Map<String, Object> save(String id, String name) {
    System.out.println("id = " + id);
    System.out.println("name = " + name);
    Map<String, Object> map = new HashMap<>();
    map.put("id", id);
    map.put("name", name);
    return map;
}

在这里插入图片描述

5、@ApiModel或@ApiModelProperty

@ApiModel(): 一般定义在实体类上
@ApiModelProperty: 一般定义在实体类里面的属性上

新建一个实体类

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户id")
    public String id;
    @ApiModelProperty("用户密码")
    public String name;
}

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

@RequestMapping("/getUser")
public User getUser(){
    return new User();
}

在这里插入图片描述

6、@ApiResponses

作用：用在请求的方法上，表示一组响应,描述响应编码对应的具体信息。
修饰范围：用在方法上

@GetMapping("/require")
@ApiResponses({
        @ApiResponse(code = 401,message = "当前请求没有被授权"),
        @ApiResponse(code = 404,message = "当前请求路径不存在"),
        @ApiResponse(code = 200,message = "保存用户信息成功"),
        @ApiResponse(code = 500,message = "加载路径失败")
})
public void require(){

}

在这里插入图片描述

5、扩展: Swagger UI页面的皮肤

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

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

在这里插入图片描述

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

在这里插入图片描述

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

在这里插入图片描述

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

在这里插入图片描述