Swagger 介绍(Swagger 与 SpringBoot 集成)

Swagger 介绍(Swagger 与 SpringBoot 集成),第1张

Swagger 介绍(Swagger 与 SpringBoot 集成)

最近我们实验室老师要我整理接口文档,我是用javadoc自动生成的(说前端人看不懂),没办法,只能换了~

本篇主要介绍 Swagger,一款围绕OpeanAPI规范构建的开源工具,便于构建和使用REST API

下面就介绍一下在Java中,SpringBoot集成Swagger的一些使用与介绍

前言 Swagger 是什么?

其是一款围绕OpeanAPI规范构建的开源工具,便于构建和使用REST API,主要Swagger工具有:

  • Swagger编辑器 - 基于浏览器的编辑器,可在其中编写OpenAPI的规范
  • Swagger UI - 让编写的OpenAPI规范以交互式API文档呈现
  • Swagger Codegen - 让编写的OpenAPI规范生成服务器静态文件(stubs)和客户端库

如果在SpringBoot集成Swaager的时候,其实它就是一个库,用于编写API文档

注解介绍

Swagger中提供了很多注解,在不同的地方使用不同的注解

注解对象范围使用位置常用参数(参数很多,常用的一些参数列举出来)例子
@Api标注类是一个Swagger资源类上String value() default “”; // 文档关于该资源描述

String[] tags() default “”; // 文档关于该资源描述
String produces() default “”; // produces (例如 “application/json, application/xml”)
String consumes() default “”;//consumes (例如 “application/json, application/xml”)
String protocols() default “”;// schemes(例如 http, https, ws, wss)
Authorization[] authorizations() default @Authorization(value = “”); //security
boolean hidden() default false; // 该资源在文档中是否被隐藏
@Api(
tags = “用户管理”,
produces = “application/json”,
consumes = “application/json”,
protocols = “http”
)
@ApiOperation描述一个API方法/类上String value(); // *** 作的描述

String notes() default “”; // *** 作的一些note
@ApiOperation(
value = “获取swagger用户”,
notes = “哈哈哈哈”
)
@ApiParamAPI参数描述方法/参数/Filed上
仅能在 JAX-RS 1.x/2.x上使用
与@ApiImplicitParam 雷同与@ApiImplicitParam 雷同
@ApiImplicitParamAPI单个参数描述方法上String name() default “”; // 参数key
String value() default “”; // 参数描述
String defaultValue() default “”; // 默认值
boolean required() default false; // 是否需要必传
boolean allowMultiple() default false; // 是否允许多值
Class dataTypeClass() default Void.class; // 数据类型
String example() default “”; // 举例
@ApiImplicitParam(
name = “id”,
value = “编号”,
defaultValue = “1”,
required = true,
allowMultiple = false,
example = “1”, dataTypeClass = String.class)
@ApiImplicitParams多个@ApiImplicitParam组成方法上ApiImplicitParam[] value(); // 多个 @ApiImplicitParam组成ApiImplicitParams(
value = {
@ApiImplicitParam(
name = “id”,
value = “编号”,
defaultValue = “1”,
required = true),
@ApiImplicitParam(
name = “name”,
value = “名称”,
defaultValue = “xxx”,
required = true)
}
)
@ApiModel对象标注为Swagger对象类上String value() default “”; // 名称
String description() default “”; // 描述
@ApiModel(
value = “返回数据对象”,
description = “返回数据”)
@ApiModelProperty对象属性方法/参数上String value() default “”;// 描述
String name() default “”; // 返回参数名称(默认是标注的参数名称)
boolean required() default false; // 是否需要必传
String dataType() default “”; // 参数类型
@ApiModelProperty(
value = “返回信息”
)
@ApiResponse返回Response,一般定义一些错误的状态码与描述信息方法/类上int code(); // 状态码
String message(); // 描述
Class response() default Void.class; // 返回数据
@ApiResponse(
code = 200,
message = “获取成功”
)
@ApiResponses多个@ApiResponse组成方法/类上ApiResponse[] value(); // 多个 @ApiResponse@ApiResponses(
value = {
@ApiResponse(
code = 200,
message = “获取成功”
),
@ApiResponse(
code = 200,
message = “获取成功”
)
} )
使用

主要介绍 Swagger 与 SpringBoot项目集成

1、导包

使用即先导包

<properties>
     <swagger.version>2.9.2swagger.version>
properties>

<dependency>
     <groupId>io.springfoxgroupId>
     <artifactId>springfox-swagger2artifactId>
     <version>${swagger.version}version>
dependency>
<dependency>
     <groupId>io.springfoxgroupId>
     <artifactId>springfox-swagger-uiartifactId>
     <version>${swagger.version}version>
dependency>
2、配置

编写Swagger配置类 SwaggerConfig

@EnableSwagger2
@Configuration
public class SwaggerConfig {
	// 核心 createRestApi
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))//扫描com 路径下的api文档
                .paths(PathSelectors.any()) //路径判断
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger Study")//标题
                .description("开发规范详文档细地址")//描述
                .version("1.1.1")//版本号
                .build();
    }

}
3、使用

举例对上述各个注解进行使用介绍

1)@ApiModel 与 @ApiModelProperty 的使用,主要用于 实体类上,标注对象与对象参数的信息

@ApiModel(value = "返回数据对象", description = "返回数据")
@Data
public class Response<T> {
    @ApiModelProperty(value = "状态码")
    private Integer code;

    @ApiModelProperty(value = "返回信息")
    private String msg;

    @ApiModelProperty(value = "返回数据")
    private T data;
}

@Data
public class User {
    @ApiModelProperty(value = "用户的姓名,比如'李四'")
    private String name;
    @ApiModelProperty(value = "id", required = true)
    private String id;
    @ApiModelProperty(value = "用户的年龄,比如:20")
    private Integer age;
}

2)@Api 、 @ApiImplicitParams 、 @ApiOperation 、@ApiResponse 的使用,主要用于Controller 类上

@RestController
@Api(tags = "用户管理", produces = "application/json", consumes = "application/json", protocols = "http")
@RequestMapping("/api/v1")
public class SwaggerController {
	// 接口参数具体描述
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id", value = "编号", defaultValue = "1", required = true, allowMultiple = true),
    })
    // 返回状态码与描述
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "获取成功咯~"),
            @ApiResponse(code = 500, message = "服务器错误咯~")}
    )
    // 接口 *** 作
    @ApiOperation("获取swagger用户")
    @GetMapping("/swagger/user2")
    public Response<User> getUser2(String id) {
        User user = new User();
        user.setAge(1);
        user.setId("1");
        user.setName("haha");
        Response<User> userResponse = new Response<>();
        userResponse.setCode(200);
        userResponse.setData(user);
        userResponse.setMsg(" *** 作成功");
        return userResponse;
    }
}

启动成功后,接口文档地址如下:

http://localhost:8081/swagger-ui.html

以上的相应信息展示图如下:

欢迎分享,转载请注明来源:内存溢出

原文地址: http://outofmemory.cn/langs/788985.html

(0)
打赏 微信扫一扫 微信扫一扫 支付宝扫一扫 支付宝扫一扫
上一篇 2022-05-05
下一篇 2022-05-05

发表评论

登录后才能评论

评论列表(0条)

保存