关于springboot:SpringBoot-优雅整合Swagger-Api-自动生成文档

一个好的可继续交付的我的项目，我的项目阐明，和接口文档是必不可少的，swagger api 就能够帮咱们很容易主动生成 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 罕用注解

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

参数：

tags：阐明该类的作用，参数是个数组，能够填多个。
value=” 该参数没什么意义，在 UI 界面上不显示，所以不必配置 ”
description = “ 用户根本信息操作 ”

ApiOperation 标记

用于申请的办法上示意一个 http 申请的操作

参数:

value 用于办法形容
notes 用于提醒内容
tags 能够从新分组（视状况而用）

ApiParam 标记

用于申请办法上对申请参数，字段阐明；示意对参数的增加元数据（阐明或是否必填等）

参数：

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

ApiModel 标记

用于 java 实体类上示意对类进行阐明，用于参数用实体类接管

参数：

value–示意对象名
description–形容
都可省略
### ApiModelProperty 标记
用于办法，字段；示意对 model 属性的阐明或者数据操作更改

参数：
value–字段阐明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
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
}

用于申请类或者办法上，能够不被 swagger 显示在页面上

用于办法示意独自的申请参数

用于办法，蕴含多个 @ApiImplicitParam

参数：

name–参数名
value–参数阐明
dataType–数据类型
paramType–参数类型
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:SpringBoot-优雅整合Swagger-Api-自动生成文档

前言

整合 swagger api

自定义配置信息

简略应用

Api 标记

ApiOperation 标记

ApiParam 标记

ApiModel 标记

ApiIgnore 标记

ApiImplicitParam 标记

ApiImplicitParams 标记

总结