配置接口注解和文档说明

README.md

@@ -1,3 +1,27 @@
 # spring-boot-openapi
 
-springboot下的openapi功能测试，包含有Swagger和springdoc
+> SpringBoot下的OpenApi功能测试，包含有Swagger和SpringDoc,对于SpringBoot下Swagger相关功能配置和授权相关，授权如 apikey,basic,oauth2,jwt等
+
+
+项目环境
+-  jdk1.8
+-   Maven 3.8.1
+-   spring-boot 2.7.16
+- springdoc-openapi-ui 1.7.0
+- springfox-boot-starter 3.0.0
+
+## 1. 项目结构
+
+```cmd
+├─spring-boot-model                 # 项目测试实体 
+├─spring-boot-springdoc             # SpringBoot集成SpringDoc
+└─spring-boot-swagger               # SpringBoot集成SpringFox(这里使用的是最后的版本Swagger3.0,其中SwaggerConfig配置的是SWAGGER_2，SwaggerOpenApiConfig.java配置的是OAS_30)
+```
+## 2. 具体演示
+
+- SpringFox Swagger
+  ![img/Swagger.png](img/Swagger.png)
+- Spring Doc
+   ![img/img.png](img/img.png)
+- oauth2 
+  ![img/oauth2.png](img/oauth2.png)

pom.xml

@@ -25,6 +25,7 @@
         <!--阿里的json工具依赖-->
         <fastjson.version>2.0.32</fastjson.version>
         <swagger.version>3.0.0</swagger.version>
+        <springdoc.version>1.7.0</springdoc.version>
         <java.version>1.8</java.version>
     </properties>
 
@@ -42,6 +43,12 @@
                 <version>${fastjson.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>org.springdoc</groupId>
+                <artifactId>springdoc-openapi-ui</artifactId>
+                <version>${springdoc.version}</version>
+            </dependency>
+
             <dependency>
                 <groupId>io.springfox</groupId>
                 <artifactId>springfox-boot-starter</artifactId>

spring-boot-springdoc/pom.xml

@@ -28,7 +28,6 @@
         <dependency>
             <groupId>org.springdoc</groupId>
             <artifactId>springdoc-openapi-ui</artifactId>
-            <version>1.7.0</version>
         </dependency>
 
     </dependencies>

spring-boot-swagger/src/main/java/com/jnssd/config/SwaggerOpenApiConfig.java

@@ -1,5 +1,6 @@
 package com.jnssd.config;
 
+import io.swagger.annotations.ApiOperation;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.util.AntPathMatcher;
@@ -39,9 +40,10 @@ public class SwaggerOpenApiConfig {
                 .select()
                 // 扫描特定包
                 // 扫描所有有注解的api，用这种方式更灵活
-                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
+                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                 //.apis(RequestHandlerSelectors.any())
-                .apis(RequestHandlerSelectors.basePackage("com.jnssd"))
+                // 扫描指定包下的
+                // .apis(RequestHandlerSelectors.basePackage("com.jnssd"))
                 .paths(PathSelectors.any())
                 .build()
                 .securitySchemes(initSecuritySchemeList())
@@ -51,7 +53,7 @@ public class SwaggerOpenApiConfig {
     public ApiInfo apiInfo() {
         return new ApiInfoBuilder()
                 .title("Swagger项目测试")
-                .description("novel项目接口文档")
+                .description("Swagger项目接口文档")
                 .build();
     }
 
@@ -59,14 +61,14 @@ public class SwaggerOpenApiConfig {
 
         List<SecurityScheme> list = new ArrayList<>();
         list.add(httpAuthenticationScheme());
-        // list.add(securitySchemeApiKey());
+        list.add(securitySchemeApiKey());
-        // list.add(securitySchemeOpenIdConnect());
+        list.add(securitySchemeOpenIdConnect());
-        //
+
-        // // 配置oauth2的几种模式
+        // 配置oauth2的几种模式
-        // list.add(securitySchemeOauth2ClientCredentials());
+        list.add(securitySchemeOauth2ClientCredentials());
-        // list.add(securitySchemeOauth2implicit());
+        list.add(securitySchemeOauth2implicit());
-        // list.add(securitySchemeOauth2Password());
+        list.add(securitySchemeOauth2Password());
-        // list.add(securitySchemeOauth2AuthorizationCode());
+        list.add(securitySchemeOauth2AuthorizationCode());
         return list;
     }
 

spring-boot-swagger/src/main/java/com/jnssd/controller/MenuController.java

@@ -1,13 +1,11 @@
 package com.jnssd.controller;
 
 import com.jnssd.model.Menu;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.*;
-import org.springframework.web.bind.annotation.PostMapping;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
-import java.util.Comparator;
 import java.util.List;
 import java.util.Objects;
 
@@ -20,6 +18,7 @@ import java.util.Objects;
  */
 @RestController
 @RequestMapping("/menu")
+@Api(tags = "菜单")
 public class MenuController {
 
     final static String SUCCESS_TEXT = "操作成功！";
@@ -28,12 +27,14 @@ public class MenuController {
     List<Menu> list = new java.util.ArrayList<>();
 
     @GetMapping("/")
+    @ApiOperation(value = "获取所有菜单", notes = "获取所有菜单")
     public ResponseEntity<List<Menu>> getAll() {
         return ResponseEntity.ok(list);
     }
 
     // 添加方法
     @PostMapping("add")
+    @ApiOperation(value = "添加菜单", notes = "添加菜单")
     public ResponseEntity<String> add(Menu entity) {
         try {
             entity.setId(list.size() + 1);
@@ -46,7 +47,8 @@ public class MenuController {
     }
 
     // 添加方法
-    @PostMapping("update")
+    @PutMapping("update")
+    @ApiOperation(value = "修改菜单", notes = "修改菜单")
     public ResponseEntity<Object> update(Menu entity) {
         try {
             // 修改list下面的数据
@@ -59,7 +61,8 @@ public class MenuController {
     }
 
     // 删除方法
-    @PostMapping("delete")
+    @DeleteMapping("delete")
+    @ApiOperation(value = "删除菜单", notes = "删除菜单")
     public ResponseEntity<String> delete(Menu entity) {
         try {
             boolean result = list.removeIf(e -> Objects.equals(e.getId(), entity.getId()));
@@ -70,7 +73,8 @@ public class MenuController {
     }
 
     // 查询方法
-    @PostMapping("query")
+    @GetMapping("query")
+    @ApiOperation(value = "查询菜单", notes = "查询菜单")
     public ResponseEntity<Object> query(Integer id) {
         try {
             Menu menu = (Menu) list.stream().filter(e -> Objects.equals(e.getId(), id));

spring-boot-swagger/src/main/java/com/jnssd/controller/RoleController.java

@@ -1,11 +1,10 @@
 package com.jnssd.controller;
 
 import com.jnssd.model.Role;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.*;
-import org.springframework.web.bind.annotation.PostMapping;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 import java.util.Objects;
@@ -18,7 +17,8 @@ import java.util.Objects;
  * @since 2023-10-12 16:32:38
  */
 @RestController
-@RequestMapping("/Role")
+@RequestMapping("/role")
+@Api(tags = "角色")
 public class RoleController {
 
     final static String SUCCESS_TEXT = "操作成功！";
@@ -27,12 +27,14 @@ public class RoleController {
     List<Role> list = new java.util.ArrayList<>();
 
     @GetMapping("/")
+    @ApiOperation(value = "获取所有角色", notes = "获取所有角色")
     public ResponseEntity<List<Role>> getAll() {
         return ResponseEntity.ok(list);
     }
 
     // 添加方法
     @PostMapping("add")
+    @ApiOperation(value = "添加角色", notes = "添加角色")
     public ResponseEntity<String> add(Role entity) {
         try {
             entity.setId(list.size() + 1);
@@ -45,7 +47,8 @@ public class RoleController {
     }
 
     // 添加方法
-    @PostMapping("update")
+    @PutMapping("update")
+    @ApiOperation(value = "修改角色", notes = "修改角色")
     public ResponseEntity<Object> update(Role entity) {
         try {
             // 修改list下面的数据
@@ -58,7 +61,8 @@ public class RoleController {
     }
 
     // 删除方法
-    @PostMapping("delete")
+    @DeleteMapping("delete")
+    @ApiOperation(value = "删除角色", notes = "删除角色")
     public ResponseEntity<String> delete(Role entity) {
         try {
             boolean result = list.removeIf(e -> Objects.equals(e.getId(), entity.getId()));
@@ -69,7 +73,8 @@ public class RoleController {
     }
 
     // 查询方法
-    @PostMapping("query")
+    @GetMapping("query")
+    @ApiOperation(value = "查询角色", notes = "查询角色")
     public ResponseEntity<Object> query(Integer id) {
         try {
             Role role = (Role) list.stream().filter(e -> Objects.equals(e.getId(), id));

spring-boot-swagger/src/main/java/com/jnssd/controller/UserController.java

@@ -1,11 +1,10 @@
 package com.jnssd.controller;
 
 import com.jnssd.model.User;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.*;
-import org.springframework.web.bind.annotation.PostMapping;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 import java.util.Objects;
@@ -19,6 +18,7 @@ import java.util.Objects;
  */
 @RestController
 @RequestMapping("/user")
+@Api(tags = "用户")
 public class UserController {
 
     final static String SUCCESS_TEXT = "操作成功！";
@@ -27,12 +27,14 @@ public class UserController {
     List<User> list = new java.util.ArrayList<>();
 
     @GetMapping("/")
+    @ApiOperation(value = "获取所有用户", notes = "获取所有用户")
     public ResponseEntity<List<User>> getAll() {
         return ResponseEntity.ok(list);
     }
 
     // 添加方法
     @PostMapping("add")
+    @ApiOperation(value = "添加用户", notes = "添加用户")
     public ResponseEntity<String> add(User entity) {
         try {
             entity.setId(list.size() + 1);
@@ -45,7 +47,8 @@ public class UserController {
     }
 
     // 添加方法
-    @PostMapping("update")
+    @PutMapping("update")
+    @ApiOperation(value = "修改用户", notes = "修改用户")
     public ResponseEntity<Object> update(User entity) {
         try {
             // 修改list下面的数据
@@ -58,7 +61,8 @@ public class UserController {
     }
 
     // 删除方法
-    @PostMapping("delete")
+    @DeleteMapping("delete")
+    @ApiOperation(value = "删除用户", notes = "删除用户")
     public ResponseEntity<String> delete(User entity) {
         try {
             boolean result = list.removeIf(e -> Objects.equals(e.getId(), entity.getId()));
@@ -69,7 +73,8 @@ public class UserController {
     }
 
     // 查询方法
-    @PostMapping("query")
+    @GetMapping("query")
+    @ApiOperation(value = "查询用户", notes = "查询用户")
     public ResponseEntity<Object> query(Integer id) {
         try {
             User user = (User) list.stream().filter(e -> Objects.equals(e.getId(), id));