介绍

• 开发中的接口文档很重要
• 我最开始时使用postman手写，后面用了apidoc，最后才用的swagger
• 说说swagger吧
  • 功能很强大
  • 自带的参数判空验证很鸡肋
    • 脱离了swagger的前端页面就完全失去了作用
  • 对代码的入侵特别大
    • 到处都是他的注解
    • 还有很多配置文件
  • 为什么还要用呢
    • 他们都用为了统一
      • 我又开始是拒绝的，其实apidoc很不错的
    • 自动化程度高
      • 建立在注解的基础上的
    • 文档清晰
      • 建立在更换了UI界面基础上的
      • 原生的像屎
• 此模块满足了以下功能
  • 将一些配置提取到了配置文件
    • 虽然现在新的版本好像自己就做了，但是我弄的时候没有
  • 使用了开源UI界面把原生的替换掉了

引入依赖

<dependency>
   <groupId>cn.jdevelops</groupId>
   <artifactId>doc-swagger-boot</artifactId>
   <version>2.0.6</version>
</dependency>

使用

前置提示

1. 配置下包扫描就行了（默认扫描的是cn.jdevelops.controller）
2. 其他的配置看注释把 cn.jdevelops.doc.core.swagger.bean.SwaggerBean

   设置controller扫描路径

   2.0.6 开始 base-package可以设置多个，并以分号分隔

   • eg. package.api1;package.api2

jdevelops.swagger.base-package=cn.tannn.swagger.controller
# springboot 2.6.x 会报错，所以加上这个
spring.mvc.pathmatch.matching-strategy=ant-path-matcher

访问文档地址

注意写个接口测测看，能不能加载接口

1. http://127.0.0.1:8080/doc.html
2. 
3. 

   调用试试

   

   接口分组

   

使用方法

1. 新增配置类继承 SwaggerConfig
2. 注意此功能会跟配置文件配置的扫描包共用，配置文件是默认的分组 ```java package cn.tannn.swagger.config;

import cn.jdevelops.doc.swagger.boot.core.SwaggerConfig; import org.springframework.context.annotation.Bean; import org.springframework.stereotype.Component; import springfox.documentation.spring.web.plugins.Docket;

/**

• 自定义接口文档分类 *
• @author tnnn
• @version V1.0

• @date 2022-09-02 09:28 */ @Component public class Knife4jConfig extends SwaggerConfig {

  @Bean(value = “groupapi1”) public Docket apiGroup_1() {

   return createRestApi("聚合文档1", "cn.tannn.swagger.groupapi1");

  }

@Bean(value = "groupapi2")
public Docket apiGroup_2() {
    return createRestApi("聚合文档2", "cn.tannn.swagger.groupapi2");
}

}

<a name="ioStT"></a>
## 提示
1. 默认全部接口都 _**添加全局**_`_**Header token**_`_**参数 **_** **
   1. ![image.png](https://cdn.nlark.com/yuque/0/2022/png/1642320/1650880065857-4394c9bd-730f-448b-9a07-d88ce9e597a9.png#clientId=ud9a9653e-c057-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=201&id=u6af0a5ad&margin=%5Bobject%20Object%5D&name=image.png&originHeight=181&originWidth=1458&originalType=binary&ratio=1&rotation=0&showTitle=false&size=11041&status=done&style=none&taskId=u8e95b817-be83-4ecc-8b3b-60526eadfb4&title=&width=1620.0000429153454)
2. 删除 全局的请求头
   1. 在配置文件中加入 `**jdevelops.swagger.add-header-token**=**false**`
<br />
<a name="Lazq8"></a>
# 注意
<a name="gcXEc"></a>
## springboot 2.6 报错
> documentationPluginsBootstrapper NullPointerException
<a name="pKOAg"></a>
### 处理办法
> [https://github.com/xiaoymin/swagger-bootstrap-ui/issues/396](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/396)
```properties
spring.mvc.pathmatch.matching-strategy=ant-path-matcher

2.0.6 版本打开接口地址无请求地址

  spring: 
      mvc:
        pathmatch:
          matching-strategy: ant-path-matcher

SpringBoot访问doc.html页面404

https://doc.xiaominfo.com/docs/faq/springboot-404

@SpringBootApplication
public class SwaggerBootstrapUiDemoApplication  implements WebMvcConfigurer{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

示例项目地址

https://github.com/en-o/Jdevelops-Example/tree/main/Swagger