Spring Boot 整合 Swagger（knife4j）

Spring Boot 整合 Swagger（knife4j）

• 1、创建一个Spring Boot 项目
• 2、配置Swagger
  • 2.1、 pom文件引入
  • 2.2、 SwaggerConfig文件配置信息
  • 2.3、controller层
  • 2.4、application.yml（或者是：application.properties）
  • 2.5、项目入口文件加注释
  • 2.6、运行项目使用Swagger调试接口

---

1、创建一个Spring Boot 项目

此步骤不进行详细描述；

---

2、配置Swagger

2.1、 pom文件引入

<!--lombok插件-->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索最新版本号-->
    <version>2.0.4</version>
</dependency>

---

2.2、 SwaggerConfig文件配置信息

此文件所在地方只要在 src 文件夹下即可：

代码：

package com.java.product.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.java.product.module.controller"))
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger接口调试平台")
                .description("基于swagger的项目接口调试平台")
                .termsOfServiceUrl("http://localhost:8999/")
                .version("1.0")
                .build();
    }
}

上述代码可复制直接使用，其中唯一必须要改的便是 Swagger 需要扫描的 Controller 层的路径；

---

2.3、controller层

代码：

package com.example.product.modules.controller;

import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.math.BigInteger;import java.security.MessageDigest;
import java.util.HashMap;
import java.util.Map;

@RestController@Api(value = "Swagger-module", tags = "Swagger-module")
@RequestMapping("/swagger")
public class SwaggerController {
    
    @GetMapping("/test/{id}")
    @ApiOperationSupport(order = 3)
    @ApiOperation(value = "测试", notes = "随意传入一个字符串")
    public Map page(@PathVariable("id")String id) {
        Map map = new HashMap();
        map.put("result", 200);
        map.put("value", this.getMD5String(id));
        return map;
    }
    
    public static String getMD5String(String str) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            md.update(str.getBytes());
            return new BigInteger(1, md.digest()).toString(16);
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }
}

此代码中只需要了解以下几个点即可：

• @Api(value = “Swagger-module”, tags = “Swagger-module”) ：代表的是模块名，在swagger平台中会以作为每个模块的名称
• @ApiOperation(value = “测试”, notes = “随意传入一个字符串”)：代表的是模块下的各个接口的名称；
• 另外需要注意的是，一般情况下如果模块下没有接口或者所有接口均没有添加swagger的接口注解，那么在swagger的调试平台中此模块也不会显示；

2.4、application.yml（或者是：application.properties）

---

2.5、项目入口文件加注释

---

2.6、运行项目使用Swagger调试接口

项目正常启动后在浏览器中输入：http://localhost:2021/doc.html#/home （上一步中的服务端口设定是多少，不要忘记把此地址的端口也要保持一致；），回车后会进入如下界面：

如此情况即算是Swagger已经配置好了，下面调试一下接口试试；
打开自定义的模块名，找到其下的接口，如下所示：

点击 测试 接口中 调试 按钮，并在 id 参数栏中输入任意字符串后点击 发送 会得到如下所示的数据：

说明接口调用成功并成功返回了传入数据的MD5加密后的数据，因此，调试成功；

---