当前位置 : 主页 > 编程语言 > java >

SpringBoot如何优雅的整合Swagger Api自动生成文档

来源：互联网 收集：自由互联 发布时间：2021-08-21
目录 前言 整合swagger api 自定义配置信息 简单使用 Swagger常用注解 Api标记 ApiOperation标记 ApiParam标记 ApiModel标记 ApiModelProperty标记 ApiIgnore标记 ApiImplicitParam标记 ApiImplicitParams标记 总结 前
目录
  • 前言
  • 整合swagger api
    • 自定义配置信息
    • 简单使用
    • Swagger常用注解
      • Api标记
      • ApiOperation标记
      • ApiParam标记
      • ApiModel标记
      • ApiModelProperty标记
      • ApiIgnore标记
      • ApiImplicitParam标记
      • ApiImplicitParams标记
  • 总结

    前言

    一个好的可持续交付的项目，项目说明，和接口文档是必不可少的，swagger api 就可以帮我们很容易自动生成api 文档，不需要单独额外的去写，无侵入式，方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目，剩余的时间就可以去约妹子啦

    整合swagger api

    这里我们自己去整合swagger api比较麻烦，要导入好几个包，有大神帮我们写好了轮子kinfe4j直接对应SpringBoot的启动项，而且在不影响原来使用功能上界面ui做了美化功能做了增强 我们直接整合这个就好了

            <!--api 文档-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.1</version>
        </dependency>

    正如官网所说

    kinfe4j官方文档点击这里

    自定义配置信息

    为我们为swagger配置更多的接口说明

    package cn.soboys.core.config;

import cn.hutool.core.collection.CollUtil;
import cn.soboys.core.ret.ResultCode;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import javax.annotation.Resource;
import java.util.Arrays;
import java.util.List;

/**
 * @author kenx
 * @version 1.0
 * @date 2021/6/21 16:02
 * api 配置类
 */
@Configuration
public class SwaggerConfigure {
    @Resource
    private SwaggerProperty swaggerProperty;

    /**
     * 构造api 文档
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).globalResponses(HttpMethod.POST, this.responseList()) //全局respons信息
                .apiInfo(apiInfo(swaggerProperty))  //文档信息
                .select()
                //文档扫描
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //有ApiOperation注解的controller都加入api文档
                .apis(RequestHandlerSelectors.basePackage(swaggerProperty.getBasePackage())) //包模式
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(SwaggerProperty swagger) {
        return new ApiInfoBuilder()
                //标题
                .title(swagger.getTitle())
                //描述
                .description(swagger.getDescription())
                //创建联系人信息 （作者，邮箱，网站）
                .contact(new Contact(swagger.getAuthor(), swagger.getUrl(), swagger.getEmail()))
                //版本
                .version(swagger.getVersion())
                //认证
                .license(swagger.getLicense())
                //认证协议
                .licenseUrl(swagger.getLicenseUrl())
                .build();
    }

    /**
     * 全局response 返回信息
     * @return
     */
    private List<Response> responseList() {
        List<Response> responseList = CollUtil.newArrayList();
        Arrays.stream(ResultCode.values()).forEach(errorEnum -> {
            responseList.add(
                    new ResponseBuilder().code(errorEnum.getCode().toString()).description(errorEnum.getMessage()).build()
            );
        });
        return responseList;
    }
}

    抽出api文档配置模版信息为属性文件方便复用

    package cn.soboys.core.config;

import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringBootConfiguration;

/**
 * @author kenx
 * @version 1.0
 * @date 2021/6/21 16:01
 * api 文档信息
 */
@Data
@SpringBootConfiguration
public class SwaggerProperty {
    /**
     * 需要生成api文档的 类
     */
    @Value("${swagger.basePackage}")
    private String basePackage;
    /**
     * api文档 标题
     */
    @Value("${swagger.title}")
    private String title;
    /**
     * api文档 描述
     */
    @Value("${swagger.description}")
    private String description;
    /**
     * api文档 版本
     */
    @Value("${swagger.version}")
    private String version;
    /**
     * api  文档作者
     */
    @Value("${swagger.author}")
    private String author;
    /**
     * api 文档作者网站
     */
    @Value("${swagger.url}")
    private String url;
    /**
     * api文档作者邮箱
     */
    @Value("${swagger.email}")
    private String email;
    /**
     * api 文档 认证协议
     */
    @Value("${swagger.license}")
    private String license;
    /**
     * api 文档 认证 地址
     */
    @Value("${swagger.licenseUrl}")
    private String licenseUrl;
}

    简单使用

    在你的Controller上添加swagger注解

    @Slf4j
@Api(tags = "登录")
public class LoginController {
    private final IUsersService userService;

    @PostMapping("/login")
    @ApiOperation("用户登录")
    public String login(@RequestBody UserLoginParams userLoginParams) {
        Users u = userService.login(userLoginParams);
        return "ok";
    }
}

    注意如启用了访问权限，还需将swagger相关uri允许匿名访问

    /swagger**/**
/webjars/**
/v3/**
/doc.html

    重启服务，自带api文档访问链接为/doc.html界面如下:

    相比较原来界面UI更加漂亮了，信息更完善功能更强大

    Swagger常用注解

    Api标记

    用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

    参数：

    • tags：说明该类的作用，参数是个数组，可以填多个。
    • value="该参数没什么意义，在UI界面上不显示，所以不用配置"
    • description = "用户基本信息操作"

    ApiOperation标记

    用于请求的方法上表示一个http请求的操作

    参数:

    • value用于方法描述
    • notes用于提示内容
    • tags可以重新分组（视情况而用）

    ApiParam标记

    用于请求方法上对请求参数，字段说明；表示对参数的添加元数据（说明或是否必填等）

    参数：

    • name–参数名
    • value–参数说明
    • required–是否必填

    ApiModel标记

    用于java实体类上表示对类进行说明，用于参数用实体类接收

    参数：

    • value–表示对象名
    • description–描述
      都可省略

    ApiModelProperty标记

    用于方法，字段； 表示对model属性的说明或者数据操作更改

    参数：

    1. value–字段说明
    2. name–重写属性名字
    3. dataType–重写属性类型
    4. required–是否必填
    5. example–举例说明
    6. hidden–隐藏
    @ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;
 
      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

    ApiIgnore标记

    用于请求类或者方法上，可以不被swagger显示在页面上

    ApiImplicitParam标记

    用于方法表示单独的请求参数

    ApiImplicitParams标记

    用于方法，包含多个 @ApiImplicitParam

    参数：

    1. name–参数名
    2. value–参数说明
    3. dataType–数据类型
    4. paramType–参数类型
    5. example–举例说明
      @ApiOperation("查询测试")
  @GetMapping("select")
  //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
  @ApiImplicitParams({
  @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
  @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
  public void select(){
 
  }

    总结

    • 可以给实体类和接口添加注释信息
    • 接口文档实时更新
    • 在线测试
    • kinfe4j 在swagger API只做增强，不会改变原有任何使用，更多增加使用功能

    点击这里进入kinfe4j官网文档

    到此这篇关于SpringBoot如何优雅的整合Swagger Api自动生成文档的文章就介绍到这了,更多相关SpringBoot整合Swagger Api内容请搜索自由互联以前的文章或继续浏览下面的相关文章希望大家以后多多支持自由互联！

    上一篇：springboot扫描引入jar包的service等组件方式
    下一篇：使用Feign远程调用时,序列化对象失败的解决
    网友评论
    相关栏目
    最近更新
    热门文章