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

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

目录前言整合swagger api自定义配置信息简单使用Swagger常用注解Api标记ApiOperation标记ApiParam标记ApiModel标记ApiModelProperty标记ApiIgnore标记ApiImplicitParam标记ApiImplicitParams标记总结

前言

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

整合swagger api

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

com.github.xiaoymin

knife4j-spring-boot-starter

3.0.1

正如官网所说

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 responseList() {

List 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;

/**

*/

@Value("${swagger.author}")

private String author;

/**

*/

@Value("${swagger.url}")

private String url;

/**

*/

@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属性的说明或者数据操作更改

参数：

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 idList;

//省略get/set

}

ApiIgnore标记

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

ApiImplicitParam标记

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

ApiImplicitParams标记

用于方法，包含多个 @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(){

}

总结

可以给实体类和接口添加注释信息

接口文档实时更新

在线测试

http:// kinfe4j 在swagger API只做增强，不会改变原有任何使用，更多增加使用功能

点击这里进入kinfe4j官网文档

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。