使基于OpenApi3并集成SpringDoc和Knife4j

2 years ago · 511785edf0
parent 25eb223fc4
commit 511785edf0
8 changed files with 162 additions and 95 deletions
--- a/swagger_study/pom.xml
+++ b/swagger_study/pom.xml
@ -23,30 +23,25 @@
        </dependency>

        <dependency>
-            <groupId>io.springfox</groupId>
-            <artifactId>springfox-swagger2</artifactId>
-            <version>2.9.2</version>
-            <exclusions>
-                <exclusion>
-                    <groupId>io.swagger</groupId>
-                    <artifactId>swagger-models</artifactId>
-                </exclusion>
-            </exclusions>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-configuration-processor</artifactId>
+            <optional>true</optional>
        </dependency>

        <dependency>
-            <groupId>io.swagger</groupId>
-            <artifactId>swagger-models</artifactId>
-            <version>1.5.22</version>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-springdoc-ui</artifactId>
+            <version>3.0.3</version>
        </dependency>

        <dependency>
-            <groupId>io.springfox</groupId>
-            <artifactId>springfox-swagger-ui</artifactId>
-            <version>2.9.2</version>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-ui</artifactId>
+            <version>1.6.14</version>
        </dependency>


+
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
--- a/swagger_study/src/main/java/cc/bnblogs/swagger_study/config/DocInfo.java
+++ b/swagger_study/src/main/java/cc/bnblogs/swagger_study/config/DocInfo.java
@ -0,0 +1,22 @@
+package cc.bnblogs.swagger_study.config;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+/**
+ * @description:
+ * @author: zfp@bnblogs.cc
+ * @date: 2023/3/5 21:15
+ */
+@Data
+@Component
+@ConfigurationProperties(prefix = "doc-info")
+public class DocInfo {
+
+    private String title = "SpringBoot集成SpringDoc";
+    private String description = "简单使用入门";
+    private String version = "1.0";
+    private String websiteName = "blog";
+    private String websiteUrl = "https://hugo.bnblogs.cc";
+}
--- a/swagger_study/src/main/java/cc/bnblogs/swagger_study/config/SpringDocConfig.java
+++ b/swagger_study/src/main/java/cc/bnblogs/swagger_study/config/SpringDocConfig.java
@ -0,0 +1,57 @@
+package cc.bnblogs.swagger_study.config;
+
+
+import io.swagger.v3.oas.models.ExternalDocumentation;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springdoc.core.GroupedOpenApi;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+
+/**
+ * @description: SpringDoc配置
+ * @author: zfp@bnblogs.cc
+ * @date: 2023/3/5 20:25
+ */
+@Configuration
+public class SpringDocConfig {
+    @Autowired
+    private DocInfo docInfo;
+    @Bean
+    public OpenAPI myOpenAPI() {
+        return new OpenAPI()
+                .info(new Info().title(docInfo.getTitle())
+                        .description(docInfo.getDescription())
+                        .version(docInfo.getVersion()))
+                .externalDocs(new ExternalDocumentation().description(docInfo.getWebsiteName())
+                        .url(docInfo.getWebsiteUrl()));
+    }
+
+
+    @Bean
+    public GroupedOpenApi allApi() {
+        return GroupedOpenApi.builder()
+                .group("all")
+                .pathsToMatch("/**")
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi DemoApi() {
+        return GroupedOpenApi.builder()
+                .group("demo")
+                .pathsToMatch("/demo/**")
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi helloApi() {
+        return GroupedOpenApi.builder()
+                .group("hello")
+                .pathsToMatch("/hello/**")
+                .build();
+    }
+
+}
--- a/swagger_study/src/main/java/cc/bnblogs/swagger_study/config/SwaggerConfig.java
+++ b/swagger_study/src/main/java/cc/bnblogs/swagger_study/config/SwaggerConfig.java
@ -1,24 +1,5 @@
 package cc.bnblogs.swagger_study.config;

-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.core.env.Environment;
-import org.springframework.core.env.Profiles;
-import springfox.documentation.builders.ParameterBuilder;
-import springfox.documentation.schema.ModelRef;
-import springfox.documentation.service.Parameter;
-import springfox.documentation.swagger2.annotations.EnableSwagger2;
-import org.springframework.context.annotation.Bean;
-import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
-import springfox.documentation.builders.RequestHandlerSelectors;
-import springfox.documentation.service.ApiInfo;
-import springfox.documentation.service.Contact;
-import springfox.documentation.spi.DocumentationType;
-import springfox.documentation.spring.web.plugins.Docket;
-
-import java.util.ArrayList;
-import java.util.List;


 /**
@ -26,50 +7,50 @@ import java.util.List;
 * @author: zfp@bnblogs.cc
 * @date: 2023/3/5 0:00
 */
-
-@EnableSwagger2
-@Configuration
-public class SwaggerConfig {
-    @Bean
-    public Docket docket(){
-        // 新建一个全局参数
-        Parameter token = new ParameterBuilder().name("token")
-                // 描述信息
-                .description("用户登录令牌")
-                // 该参数放在请求头
-                .parameterType("header") // 也可以设置query参数，相当于@RequestParam
-                // 参数的类型
-                .modelRef(new ModelRef("String"))
-                // 该参数必填
-                .required(true)
-                .build();
-
-        List<Parameter> parameters = new ArrayList<>();
-        parameters.add(token);
-
-        return new Docket(DocumentationType.SWAGGER_2)
-                .globalOperationParameters(parameters).apiInfo(apiInfo());
-
-    }
-
+//
+//@EnableSwagger2
+//@Configuration
+//public class SwaggerConfig {
 //    @Bean
-//    public Docket RestfulApi() {
+//    public Docket docket(){
+//        // 新建一个全局参数
+//        Parameter token = new ParameterBuilder().name("token")
+//                // 描述信息
+//                .description("用户登录令牌")
+//                // 该参数放在请求头
+//                .parameterType("header") // 也可以设置query参数，相当于@RequestParam
+//                // 参数的类型
+//                .modelRef(new ModelRef("String"))
+//                // 该参数必填
+//                .required(true)
+//                .build();
+//
+//        List<Parameter> parameters = new ArrayList<>();
+//        parameters.add(token);
+//
 //        return new Docket(DocumentationType.SWAGGER_2)
-//                .apiInfo(apiInfo())
-//                .select()
-//                .apis(RequestHandlerSelectors.basePackage("cc.bnblogs.swagger_study.controller"))
-//                .paths(PathSelectors.any()).build();
+//                .globalOperationParameters(parameters).apiInfo(apiInfo());
+//
+//    }
+//
+////    @Bean
+////    public Docket RestfulApi() {
+////        return new Docket(DocumentationType.SWAGGER_2)
+////                .apiInfo(apiInfo())
+////                .select()
+////                .apis(RequestHandlerSelectors.basePackage("cc.bnblogs.swagger_study.controller"))
+////                .paths(PathSelectors.any()).build();
+////    }
+//    private ApiInfo apiInfo() {
+//        return new ApiInfoBuilder()
+//                //页面标题
+//                .title("Spring Boot集成Swagger2构建RESTful API")
+//                //创建人
+//                .contact(new Contact("barney", "https://hugo.bnblogs.cc",  "tzhangfp@163.com"))
+//                //版本号
+//                .version("1.0")
+//                //描述
+//                .description("学习使用Swagger")
+//                .build();
 //    }
-    private ApiInfo apiInfo() {
-        return new ApiInfoBuilder()
-                //页面标题
-                .title("Spring Boot集成Swagger2构建RESTful API")
-                //创建人
-                .contact(new Contact("barney", "https://hugo.bnblogs.cc",  "tzhangfp@163.com"))
-                //版本号
-                .version("1.0")
-                //描述
-                .description("学习使用Swagger")
-                .build();
-    }
-}
+//}
--- a/swagger_study/src/main/java/cc/bnblogs/swagger_study/controller/DemoController.java
+++ b/swagger_study/src/main/java/cc/bnblogs/swagger_study/controller/DemoController.java
@ -1,28 +1,27 @@
 package cc.bnblogs.swagger_study.controller;

 import cc.bnblogs.swagger_study.pojo.Student;
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiImplicitParam;
-import io.swagger.annotations.ApiImplicitParams;
-import io.swagger.annotations.ApiOperation;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.*;

-@Api(tags = "demo接口")
+@Tag(name = "demo接口列表")
@RestController
@RequestMapping("/demo/")
 public class DemoController {
    @GetMapping
-    @ApiOperation("输出hello world")
+    @Operation(summary = "打印hello world")
    public String greet() {
        return "Hello, World";
    }

-    @PostMapping("/{id}/")
-    @ApiOperation("提交一个id")
-    @ApiImplicitParams({
-            @ApiImplicitParam(name = "id", value = "编号", example = "1"),
-            @ApiImplicitParam(name = "name", value = "姓名", example = "admin")
+    @Parameters(value={
+            @Parameter(name = "id",description = "编号",example = "1"),
+            @Parameter(name = "name",description = "姓名",example = "admin"),
    })
+    @PostMapping("/{id}/")
    public Integer addInfo(@RequestParam Integer id,
                           @RequestParam String name) {
        System.out.println(name);
--- a/swagger_study/src/main/java/cc/bnblogs/swagger_study/controller/HelloController.java
+++ b/swagger_study/src/main/java/cc/bnblogs/swagger_study/controller/HelloController.java
@ -1,5 +1,6 @@
 package cc.bnblogs.swagger_study.controller;

+import io.swagger.v3.oas.annotations.Parameter;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
--- a/swagger_study/src/main/java/cc/bnblogs/swagger_study/pojo/Student.java
+++ b/swagger_study/src/main/java/cc/bnblogs/swagger_study/pojo/Student.java
@ -1,7 +1,7 @@
 package cc.bnblogs.swagger_study.pojo;

-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
+
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
@ -14,11 +14,11 @@ import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
-@ApiModel("学生表")
+@Schema(title = "学生表")
 public class Student {
-    @ApiModelProperty("学号")
+    @Schema(title = "学号")
    private Integer id;
-    @ApiModelProperty("姓名")
+    @Schema(title = "姓名")
    private String name;

 }
--- a/swagger_study/src/main/resources/application.yml
+++ b/swagger_study/src/main/resources/application.yml
@ -2,4 +2,16 @@
 #  profiles:
 #    active: test # 当前环境为dev
 server:
-  port: 8080
+  port: 8080
+
+springdoc:
+  packages-to-scan: cc.bnblogs.swagger_study.controller
+  swagger-ui:
+    enabled: true
+
+doc-info:
+  title: SpringDoc使用
+  description: 基于Spring Boot 2.7.9
+  version: 1.2
+  website-name: bnblogs
+  website-url: https://bnblogs.cc