SpringBoot怎么整合Swagger Api自动生成文档

本篇内容主要讲解“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做了美化功能做了增强 我们直接整合这个就好了

<!--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;@Configurationpublic class SwaggerConfigure {    @Resource    private SwaggerProperty swaggerProperty;        @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();    }        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;@Data@SpringBootConfigurationpublic class SwaggerProperty {        @Value("${swagger.basePackage}")    private String basePackage;        @Value("${swagger.title}")    private String title;        @Value("${swagger.description}")    private String description;        @Value("${swagger.version}")    private String version;        @Value("${swagger.author}")    private String author;        @Value("${swagger.url}")    private String url;        @Value("${swagger.email}")    private String email;        @Value("${swagger.license}")    private String license;        @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**webjarsv3doc.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自动生成文档”有了更深的了解，不妨来实际操作一番吧！这里是编程网网站，更多相关内容可以进入相关频道进行查询，关注我们，继续学习！