SpringBoot整合超好用的API可视化接口工具swagger

最新推荐文章于 2024-09-12 09:31:50 发布

坤坤超爱打球

最新推荐文章于 2024-09-12 09:31:50 发布

阅读量1k

点赞数

分类专栏：文学 Springboot 文章标签： spring boot java swagger2

本文链接：https://blog.csdn.net/aa11dddd/article/details/109501881

版权

文学同时被 2 个专栏收录

13 篇文章 0 订阅

订阅专栏

Springboot

7 篇文章 0 订阅

订阅专栏

# SpringBoot整合-超好用的API可视化接口工具swagger

一、简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

1. 接口的文档在线自动生成。
2. 功能测试。

Swagger是一组开源项目，其中主要要项目如下：

Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。

Swagger-js: 用于JavaScript的Swagger实现。

Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、使用第三方依赖（最简单的方法）

这时对swagger的再封装：

1、在pom.xml文件中添加第三方swagger依赖（）

<dependency>
	<groupId>com.spring4all</groupId>
	<artifactId>swagger-spring-boot-starter</artifactId>
	<version>1.7.0.RELEASE</version>
</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。
3、https://gitee.com/didispace/spring-boot-starter-swagger这是码云上这个swagger依赖实现的项目，里面有详细的讲解。

下面是官方推荐使用的：

三、Springboot集成swagger

1.导入依赖

1.引入架包（记得切换匹配的版本），本文采用1.5.2.RELEASE的Springboot版本。

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<!-- 导入swagger依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>

2.新建一个swagger的启动类

2.新建swagger2类，和启动类平行目录，如图。

在这里插入图片描述

3.编写Swagger2代码

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //为当前包路径
            .apis(RequestHandlerSelectors.basePackage("com.zhang.myblog.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //页面标题
            .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
            //创建人
            .contact(new Contact("吴伟俊", "http://www.gitee.com/zzwuweijun", "1227297881@qq.com"))
            //版本号
            .version("1.0")
            //描述
            .description("API 描述")
            .description("更多请关注http://www.baidu.com")
            // // 给定一个网址，可以是自己项目的首页等等；在swagger的首页处有一个连接：Terms of service
            .termsOfServiceUrl("http://www.baidu.com")
            .build();
    }
}

4.使用

在项目的完整URL上，加上 swagger-ui.html例如：

输入网址http://localhost:8080/swagger-ui.html。

在这里插入图片描述

四、使用swagger注解

@Api

用在类上，该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性

tags API分组标签。具有相同标签的API将会被归并在一组内展示。
value 如果tags没有定义，value将作为Api的tags使用
description API的详细描述，在1.5.X版本之后不再使用，但实际发现在2.0.0版本中仍然可以使用

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

例子：

package com.wwj.helloworldquick.controller;
// ....
@Api(tags = {"one2"}, description = "对TestSwagger2类的说明")
@RestController
public class TestSwagger2 {
   @GetMapping("/swagger2")
   public String swagger() {// 无参
       return "swagger";
   }
}

在这里插入图片描述

@ApiOperation

在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

value 对操作的简单说明，长度为120个字母，60个汉字。
notes 对操作的详细说明。使用字符串 "\n"可以换行。
httpMethod HTTP请求的动作名，可选值有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。注意，这里最好是大写。
code 默认为200，有效值必须符合标准的HTTP Status Code Definitions。
response 返回的对象

属性名称	备注
value	url的路径值
notes	对操作的详细说明。
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
extensions	扩展属性

例子：

@Api(tags = {"one2"}, description = "对TestSwagger2类的说明")
@RestController
public class TestSwagger2 {
    @GetMapping("/swagger2")
    @ApiOperation(value = "访问/swagger，简单说明2", notes = "详细说明：访问/swagger，简单说明2",
                  httpMethod = "GET", code = 200, response = Person.class)
    public String swagger() {// 无参
        return "swagger";
    }
}

在这里插入图片描述

@ApiImplicitParams

用在方法上，注解ApiImplicitParam的容器类，以数组方式存储。

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

@ApiImplicitParam

对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：

name 参数名称
value 参数的简短描述
required 是否为必传参数
dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。
defaultValue：参数的默认值

例子：

@Api(tags = {"one2"}, description = "对TestSwagger2类的说明")
@RestController
public class TestSwagger2 {
    //@GetMapping("/swagger2")
    @RequestMapping("/swagger2")
    @ApiOperation(value = "访问/swagger，简单说明2", notes = "详细说明：访问/swagger，简单说明2",
                  httpMethod = "GET", code = 200, response = Person.class)
    
    @ApiImplicitParams({
        @ApiImplicitParam(value = "用户名", name = "name", required = true, dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "用户年龄", name = "age", required = true, dataType = "int", paramType = "path")
    })
    public String swagger(String name, Integer age) {
        return "swagger";
    }
}

在这里插入图片描述

@ApiParam

增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有

required 是否为必传参数
value 参数简短说明

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

@ApiResponses

注解@ApiResponse的包装类，数组结构。即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内。

@ApiResponse

描述一个操作可能的返回结果。当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。但Swagger不支持同一返回码，多种返回类型的注解。注意：这个注解必须被包含在@ApiResponses注解中。

code HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
message 更加易于理解的文本消息
response 返回类型信息，必须使用完全限定类名，比如“com.xyz.cc.Person.class”。
responseContainer 如果返回类型为容器类型，可以设置相应的值。有效值为 “List”, “Set” or “Map”，其他任何无效的值都会被忽略。

@Api(tags = {"one2"}, description = "对TestSwagger2类的说明")
@RestController
public class TestSwagger2 {
    //@GetMapping("/swagger2")
    @RequestMapping("/swagger2")
    @ApiOperation(value = "访问/swagger，简单说明2", notes = "详细说明：访问/swagger，简单说明2",
                  httpMethod = "GET", code = 200, response = Person.class)
    @ApiImplicitParams({
        @ApiImplicitParam(value = "用户名", name = "name", required = true, dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "用户年龄", name = "age", required = true, dataType = "int", paramType = "path")})

    @ApiResponses({
        @ApiResponse(code = 200, message = "成功返回，返回值类型为Person类型--》", response = Person.class),
        @ApiResponse(code = 404, message = "请求错误，都返回-1", response = Integer.class)
    })
    public String swagger(String name, Integer age) {
        return "swagger";
    }
}

在这里插入图片描述

对于Model的注解，Swagger提供了两个：@ApiModel及@ApiModelProperty，分别用以描述Model及Model内的属性。

@ApiModel

描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：

value model的别名，默认为类名
description model的详细描述

@ApiModelProperty

描述一个model的属性

对model属性的注解，主要的属性值有：

value 属性简短描述
example 属性的示例值
required 是否为必须值

@ApiIgnore

可以标志在类上和方法，都表示忽略。

五、美化界面

美化界面：
在maven中添加以下架包，采用别人封装的美化swagger界面架包。

<!-- 上面两个jar的必须的，下面这个是第三方的UI界面的美化，不是必需的 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.6</version>
</dependency>

在配置类和启动类都需要添加@EnableSwagger2注解。
————————————————

测试没起作用。。。。尴尬

六、报错

关于Swagger报错java.lang.NumberFormatException: For input string: ""的总结

https://blog.csdn.net/qq122516902/article/details/89673363

发现一种解决方法：在注解@ApiImplicitParam的example属性设置一个值就好了。

七、数组/集合参数的正确配置方式allowMultiple、dataType

转自：https://blog.csdn.net/hanchao5272/article/details/99729606?depth_1-utm_source=distribute.pc_relevant.none-task&utm_source=distribute.pc_relevant.none-task

接口参数的注解配置

// GET参数
@ApiImplicitParam(name = "list", value = "用户ID列表", paramType = "query", allowMultiple = true, dataType = "int")

// POST参数
@ApiImplicitParam(name = "list", value = "用户名称列表", paramType = "body", allowMultiple = true, dataType = "String")

// POST参数-自定义类型User
@ApiImplicitParam(name = "list", value = "用户列表", paramType = "body", allowMultiple = true, dataType = "UserDto")

主要参数：

allowMultiple：允许多个，即：数组或集合。
dataType：数组或集合的元素类型，即：类名。

自定义类型的注解配置

@ApiModel(value = "UserDto", description = "用户")
public class User implements Serializable {
  //...
}

特别的：

如果元素类型为原生类型，如：int、String之类的，无需此步骤。
如果元素类型为自定义类型，如：UserDto，则必须此步骤，以便swagger能够找到这个元素对应的类型。

坤坤超爱打球

关注

0
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录