【Swagger2】:让API文档编写变得轻松愉悦的神奇工具

发布时间:2023年12月19日

🥳🥳Welcome Huihui's Code World ! !🥳🥳

接下来看看由辉辉所写的关于Swagger2的相关操作吧?

目录

🥳🥳Welcome Huihui's Code World ! !🥳🥳

一.?Swagger2是什么

二.Swagger2有什么用

三.Swagger2怎么使用

1.导入依赖

2.创建Swagger配置类

3.使用

四.Swagger2的常用注解

1.@Api

2.@ApiOperation

3.@ApiImplicitParam

3.@ApiImplicitParams

4.@ApiModel和@ApiModelProperty

5.@ApiParam

五.Swagger2在不同环境下的状态

1.修改Swagger2配置类

2.修改application.yml

3.使用maven package打包测试

4.打开jar包


一.?Swagger2是什么

????????Swagger2是一个用于生成、描述和调用RESTful风格的Web服务的框架。它的主要功能是将项目中所有(想要暴露的)接口展现在页面上,并且可以进行接口调用和测试的服务。此外,Swagger2还遵循了OpenAPI规范,这是Linux基金会的一个项目,旨在通过提供标准和工具来促进API的开放性和可发现性。

????????在日常开发中,编写和维护接口文档是每个程序员的职责。然而,随着项目的复杂度增加,接口文档的管理变得越来越困难。这时,Swagger2就可以发挥其强大的作用。它可以快速帮助我们编写最新的API接口文档,大大减少了会议前整理各种资料的时间,从而提升了团队开发的沟通效率。

????????在Spring框架中,我们可以使用@EnableSwagger2注解来开启Swagger2相关技术。它会扫描当前类所在包以及子包中所有类型的swagger相关注解,从而实现swagger文档的定制。

二.Swagger2有什么用

????????Swagger2的主要用途在于生成、描述和调用RESTful风格的Web服务。它可以让项目中所有(想要暴露的)接口展现在页面上,并且可以进行接口调用和测试的服务。在日常开发中,编写和维护接口文档是每个程序员的职责。然而,随着项目的复杂度增加,接口文档的管理变得越来越困难。这时,Swagger2就可以发挥其强大的作用。它可以快速帮助我们编写最新的API接口文档,大大减少了会议前整理各种资料的时间,从而提升了团队开发的沟通效率。

????????Swagger2还可以给一些比较难理解的属性或者接口增加注释信息,并提供接口文档实时更新的功能,可以在线测试。通过这些功能,我们可以更高效地理解和使用接口,提升工作效率。因此,Swagger2是一个优秀的工具,对于开发者来说具有很高的实用价值。

三.Swagger2怎么使用

1.导入依赖

<!-- Swagger UI,API文档生成工具 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!-- Swagger UI Bootstrap,美化API文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2.创建Swagger配置类

package com.wh.springboot.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
// dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {

    /**
     * 创建该API的基本信息  http://项目实际地址/doc.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Swagger2")
                .description("测试系统")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("1.0.0")
                .build();
    }

    /**
     * 创建API应用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wh.springboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

3.使用

根据接口路径查询接口信息

四.Swagger2的常用注解

1.@Api

@Api注解用在类上,说明该类的作用。可以标记一个Controller类做为swagger文档资源。

属性说明
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
produces返回的格式类型例如:"application/json, application/xml"
consumes接收请求参数的类型例如:"application/json, application/xml"
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置

案例演示

@RestController
@RequestMapping("/oa-user")
@Api(tags = "用来完成用户操作的接口")
public class OaUserController {
    @Autowired
    private IOaUserService oaUserService;
    }

2.@ApiOperation

@ApiOperation注解用在方法上,说明方法的作用,每一个url资源的定义。

属性说明
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
produces返回的格式类型例如:"application/json, application/xml"
consumes接收请求参数的类型例如:"application/json, application/xml"
hidden是否在文档中显示
notes注释说明
response返回的对象
responseContainer这些对象是有效的 "List", "Set" or "Map".,其他无效
responseReference指定对响应类型的引用。指定的引用可以是本地的,也可以是远程的*将按原样使用,并覆盖任何指定的response()类
responseHeaders响应旁边提供的可能标题列表
httpMethod"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
codehttp的状态码 默认 200

案例演示

    @ApiOperation(value = "完成用户的查询")
    @RequestMapping("/list")
    public Object list(String name) {
        QueryWrapper<OaUser> wrapper =new QueryWrapper<>();
        wrapper.like("name",name);
        //简单的分页查询
        Page<OaUser> page = new Page<>(1, 5);
        Page<OaUser> res = oaUserService.page(page, wrapper);
        res.getTotal();//数据总数
        res.getPages();//数据总页数
        return res.getRecords();
    }

3.@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入;

属性说明
paramType参数放在哪个地方
name参数名称
value参数代表的含义
dataType参数类型
dataTypeClass参数类型
required是否必要
defaultValue参数的默认值

paramType

类型作用
path以地址的形式提交数据,用于restful接口。请求参数采用@PathVariable获取
query直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body以流的形式提交,仅支持POST。请求参数采用@RequestBody获取
header参数在request headers里边提交。请求参数采用@RequestHeader获取
form以form表单的形式提交,仅支持POST。

案例演示

/**
     * 增加
     * @param oaUser
     * @return
     */
    @ApiImplicitParam(name="oaUser",value="新增传进来的用户对象")
    @RequestMapping("/add")
    public Map add(OaUser oaUser){
        oaUserService.save(oaUser);
        Map map = new HashMap();
        map.put("coed",200);
        map.put("msg","添加成功");
        return map ;
    }

3.@ApiImplicitParams

@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中;

案例演示

@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
 ? ? ? ? ?  ,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
 ? ? ? ? ? ?@ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
 ? ? ? ? ? ?@ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
 ? ? ? ? ? ?@ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,
 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? @RequestParam Double price,
 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? @RequestParam String booktype){
 ? ?return bookService.insert(Book.builder()
 ? ? ?  .bookid(UUID.randomUUID().toString().replace("-",""))
 ? ? ?  .bookname(bookname)
 ? ? ?  .booktype(booktype)
 ? ? ?  .price(price)
 ? ? ?  .build());
}

4.@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;

@ApiModelProperty注解描述一个model的属性。

属性说明
value字段说明
name参数名称
dataType参数类型
hidden在文档中隐藏
required是否必要
example举例说明
notes注释说明

案例演示

package com.wh.springboot.model;

import com.baomidou.mybatisplus.annotation.*;

import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;

/**
 * <p>
 * 
 * </p>
 *
 * @author wh
 * @since 2023-12-16
 */
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_oa_user")
@ApiModel(value = "用户对象")
public class OaUser implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(value="用户编号")
    private Long id;

    /**
     * 用户名: 唯一键 登陆时使用 禁止修改
     */
    @TableField("name")
    @ApiModelProperty(value="用户名")
    private String name;

    /**
     * 用户密码:长度6~10位,MD5加密
     */
    @TableField("pwd")
    @ApiModelProperty(value="用户密码")
    private String pwd;

    /**
     * 用户角色:1 管理员 2 发起者 3 审批者 4 参与者 5 会议室管理员
     */
    @TableField("rid")
    @ApiModelProperty(value="用户角色")
    private Long rid;

    /**
     * 登录名
     */
    @TableField("loginName")
    @ApiModelProperty(value="登录名")
    private String loginName;

    /**
     * 乐观锁
     */
    @Version
    @ApiModelProperty(hidden = true)
    private Integer version;

    /**
     * 逻辑删除
     */
    @TableField("deleted")
    @ApiModelProperty(hidden = true)
    private Integer deleted;


}

注意:在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息,因为在这里的输入参数是实体对象,而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

5.@ApiParam

作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)

@ApiParam必须与@RequestParam@PathVariable@RequestHeader一起使用。

属性说明
name参数名称
value参数简单描述
defaultValue描述参数默认值
required是否为必传参数, false:非必传; true:必传
allowMultiple指定参数是否可以通过多次出现来接收多个值
hidden隐藏参数列表中的参数
example非请求体(body)类型的单个参数示例
examples@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例,仅适用于请求体类型的请求

案例演示

@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
            @ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
            @ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
            @ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
      System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
    return new JsonResponseBody<>();
}

五.Swagger2在不同环境下的状态

为了保证接口文档的安全,禁用了生产环境的加载,具体说明请看:

参考地址:生产环境中禁用swagger - 简书

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

1.修改Swagger2配置类

添加@Profile注解,指明在何种环境下可以使用Swagger2,一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2;而在生产(dev)环境下不能使用Swagger2。

package com.wh.springboot.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
// dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {

    /**
     * 创建该API的基本信息  http://项目实际地址/doc.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Swagger2")
                .description("测试系统")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("1.0.0")
                .build();
    }

    /**
     * 创建API应用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wh.springboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

2.修改application.yml

修改application.yml文件,配置项目系统的运行环境(dev/test/prod)

spring:
 ?#配置swagger2生产和测试环境不可用
  profiles:
 ?  active: dev

3.使用maven package打包测试

4.打开jar包

这样的话,生产的环境下就不能够使用swagger2了

写在最后的话

我们可以使用接口测试工具,将swagger2中的访问接口信息的接口导入进去

?

?好啦,今天的分享就到这了,希望能够帮到你呢!😊😊???

文章来源:https://blog.csdn.net/m0_74315688/article/details/135095389
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。