您好,欢迎访问代理记账网站
  • 价格透明
  • 信息保密
  • 进度掌控
  • 售后无忧

Swagger的使用

Swagger的使用

  • Swagger介绍
  • Swagger工作原理
  • 引入依赖
  • 编写Swagger配置
  • Swagger常用注解
  • 使用Swagger注解
  • Swagger接口测试

Swagger介绍

Swagger是全球最大的OpenAPI规范(OpenAPI Specification 简称OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。

特点

Swagger通过面向开发人员,架构师和产品所有者的易于使用的工具,使API设计变得轻而易举。

Swagger提供了用于生成,可视化和维护API文档的一系列解决方案,使API文档不再需要人工操作。

Swagger提供了用于快速制作原型和构建API功能的工具。

Swagger工具和ReadyAPI平台使您可以轻松地在管道中快速创建,管理和执行API测试。

Swagger工作原理

1、系统启动,扫描到工程中的Swagger配置类

2、在此类中指定了包路径cn.ybzy.controller,找到在此包下及子包下标记有@RestController注解的controller类

3、根据controller类中的Swagger注解生成接口文档。

4、启动服务,查看接口文档

引入依赖

		<!-- swagger2 配置 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<!-- swagger2相关的一个皮肤插件 -->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.9.6</version>
		</dependency>

编写Swagger配置

@Configuration
@EnableSwagger2
public class Swagger2Configuration  {

    /**
     * 配置swagger2核心配置 docket
     * http://localhost:8888/swagger-ui.html     访问swagger的原路径
     * http://localhost:8888/doc.html     访问swagger换肤的原路径
     * @return
     */
    @Bean
    public Docket createRestApi() {
        // 指定api类型为swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                // 用于定义api文档汇总信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors
                        // 指定controller包
                        .basePackage("cn.ybzy.controller"))
                // 所有controller
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档页标题
                .title("文档页标题")
                // 联系人信息
                .contact(new Contact("name",
                        "url",
                        "email"))
                // 详细信息
                .description("这是api文档")
                // 文档版本号
                .version("0.0.1")
                // 网站地址
                .termsOfServiceUrl("https://www.abc.com")
                .build();
    }

}

Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口,常用Swagger注解如下:

@Api:修饰整个类,描述Controller的作用 

@description 功能描述

@ApiOperation:描述一个类的一个方法,或者说一个接口

@ApiParam:单个参数描述 

@ApiModel:用对象来接收参数 

@tags 功能描述

@ApiModelProperty:用对象接收参数时,描述对象的一个字段 

@ApiResponse:HTTP响应其中1个描述 

@ApiResponses:HTTP响应整体描述 

@ApiIgnore:使用该注解忽略这个API 

@ApiError :发生错误返回的信息 

@ApiImplicitParam:一个请求参数

@ApiImplicitParams:多个请求参数

@ApiImplicitParam属性:

属性取值作用
paramType查询参数类型
path以地址的形式提交数据
query直接跟参数完成自动映射赋值
body以流的形式提交 仅支持POST
header参数在request headers 里边提交
form以form表单的形式提交 仅支持POST
dataType参数的数据类型 只作为标志说明,并没有实际验证
Long
String
name接收参数名
value接收参数的意义描述
required参数是否必填
true必填
false非必填
defaultValue默认值

使用Swagger注解

@RestController
@RequestMapping("/user")
@Api(value = "用户管理API", tags = "User管理相关API方法")
public class UserController {

    @GetMapping("/list/{page}/{size}")
    @ApiOperation("分页查询用户列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "页码",required=true,paramType="path",dataType="int"),
            @ApiImplicitParam(name = "size", value = "每页记录数",required=true,paramType="path",dataType="int")
    })
    public String findList(@PathVariable("page") int page, @PathVariable("size") int size, SearchParams searchParams) {
        String str="页码:"+page+",每页记录数:"+size+"接受查询参数:"+searchParams;
        return str;
    }
}

使用注解 ApiModelProperty 对属性注释:

@Data
@ApiModel(value = "用户搜索参数对象BO", description = "从客户端,由用户传入的数据封装在此entity中")
public class SearchParams {
    @ApiModelProperty(value = "用户名称", name = "name", example = "zd", required = true)
    private String name;
    @ApiModelProperty("归属公司")
    private int company;
    @ApiModelProperty("归属分公司")
    private int office;
}

Swagger接口测试

访问swagger的原路径 http://localhost:8888/swagger-ui.html
在这里插入图片描述
接口参数描述
在这里插入图片描述
接口测试
在这里插入图片描述
接口响应
在这里插入图片描述
访问swagger换肤的原路径 http://localhost:8888/doc.html
在这里插入图片描述
接口参数描述
在这里插入图片描述
接口响应
在这里插入图片描述


分享:

低价透明

统一报价,无隐形消费

金牌服务

一对一专属顾问7*24小时金牌服务

信息保密

个人信息安全有保障

售后无忧

服务出问题客服经理全程跟进