swagger增强介绍

前言

无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

基于spring的swagger框架

简介

通过Swagger衍生出来的一系列项目和工具，可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

swagger

界面一览为快

首页

接口列表

接口参数

引入maven依赖

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

添加配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * <p>
 *
 * </p>
 *
 * @date: 2021-07-27
 * @Description:
 * @JDK: 1.8
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.cvit.agg.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文档说明
                .title("数据中台")
                //文档版本说明
                .version("1.0.0")
                .build();
    }
}

访问地址

http://ip:端口/服务名/swagger-ui.html

http://localhost:8080/test/swagger-ui.html

可以看出原生的swagger界面以及展示效果并不好看

所以可以选用其他扩展框架

---

swagger扩展框架 之knife4j

优点：

1、编写少量代码
2、界面清晰
3、左边菜单，右边内容符合大多数人的习惯
4、支持文档生成，如：markdown、html、word等
5、替代Excel、文本等手写的对接文档

界面一览为快

首页

导出接口文档界面

接口调试界面

引入maven依赖

        <!-- knife4j swagger -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.7</version>
        </dependency>

添加swagger配置类

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
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.EnableSwagger2WebMvc;

/**
 * <p>
 * swagger文档开启
 * </p>
 *
 * @date: 2021-07-27
 * @Description:
 * @JDK: 1.8
 */
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    /**
     * 注册swagger文档
     *
     * @return
     */
    @Bean(value = "bigDataApi")
    public Docket bigDataApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket.groupName("数据中台").genericModelSubstitutes(ResponseEntity.class)
                .apiInfo(bigDataApiInfo()).select()
                //扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.cvit.dev.controller"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
        return docket;
    }

    /**
     * 大数据api详情
     *
     * @return
     */
    private ApiInfo bigDataApiInfo() {
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("数据中台接口文档")
                .description("该文档主要提供数据中台后端的接口"
                        + "返回：  \r"
                        + "ReturnBody<T> {\"code\":\"标识码\",\"msg\":\"描述\",data{ json字符串（对象）  } ")
                .termsOfServiceUrl("http://")
                .contact(new springfox.documentation.service.Contact("数据中台后台开发组", null, null))
                .version("1.0.0");
        ApiInfo apiInfo = apiInfoBuilder.build();
        return apiInfo;
    }

}

访问地址

http://+ip:+端口+/服务名/doc.html

http://127.0.0.1:8080/test/doc.html

---

swagger相关注解配置

添加注解

swagger注解	解释	注解位置	举例
@Api	接口类描述	Controller 类上	@Api(value = “任务监控”, tags = “任务监控”)
@ApiOperation	方法描述	方法上	@ApiOperation(value = “分页查询”)
@ApiImplicitParams	参数组	方法上	@ApiImplicitParams({@ApiImplicitParam(name = “current”, value = “当前页”), @ApiImplicitParam(name = “size”, value = “数据大小”)})
@ApiImplicitParam	参数描述	方法上	@ApiImplicitParam(name = “current”, value = “当前页”)
@ApiModel	实体类描述	实体类上	@ApiModel(“任务调度”)
@ApiModelProperty	字段描述	字段上	@ApiModelProperty(“脚本id”)

总结

knife4j官网

这里只介绍了一些基本用法，更多好用的内容，请关注官网
如果有更多拓展用法欢迎评论

转载请标明源地址 ，谢谢
https://blog.youkuaiyun.com/m0_37887812/article/details/119780411