swagger接口文档

Question

#需求：通过swagger实现接口文档
#场景：一个接口，有2个流程，2个流程需要的参数不一样，想通过swagger实现选一个流程，能知道这个流程里面需要什么参数。
例如：流程1需要：name 名称， type 类型：1,2,3
流程2需要：name 名称， type 类型：a,b,c，status 状态：t,f
我通过下面的代码实现，发现接口文档里面不能正确的显示出来所需的参数。
#硬性要求：只能一个接口
#还有一种方法，就是把TypeA和TypeB作为成员放到一个大类里面， 但是因为我有大概10多个类型，放到一个大类里面显得很傻，想看看有没有别的方法，在线请教

@Data
public class TypeA {
    @Schema(description = "姓名", required = true)
    private String name;

    @Schema(description = "类型：1-普通， 2-中等，3-高级", )
    private Integer type;
    ···
    此处忽略20个参数
}

@Data
public class TypeB {
    @Schema(description = "姓名", required = true)
    private String name;

    @Schema(description = "类型：a-低速， b-普通，c-高速")
    private String type;

    @Schema(description = "t-成功，f-失败")
    private String status;
    ···
    此处忽略20个参数
}

@RestController
@RequestMapping("/api")
public class TestGroupContorller {
    @PostMapping("/your-endpoint")
    @Operation(summary = "Example endpoint with grouped parameters",
            requestBody = @RequestBody(content = {
                    @Content(mediaType = "application/json", schema = @Schema(oneOf = {TypeA.class, TypeB.class}))
            }),
            responses = {
                    @ApiResponse(description = "Successful response", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseMessage.class)))
            })
    public ResponseEntity<ResponseMessage> yourEndpoint(@org.springframework.web.bind.annotation.RequestBody RequestType request) {
        // Your endpoint implementation
        return ResponseEntity.ok(new ResponseMessage("Success"));
    }

    static class ResponseMessage {
        private String message;

        public ResponseMessage(String message) {
            this.message = message;
        }

    }
}

Answer 1

以下内容由AIGC及阿里嘎多学长共同生成、有用望采纳：

---

你的代码示例和需求描述已经很清晰了，以下是一些建议和改进点，帮助你更好地实现你的需求：

1. 实现接口文档：

   • 确保Swagger注解正确使用，特别是@Schema和@Operation注解。
   • 使用@Schema注解来描述参数和返回值，确保每个参数的描述和类型都被正确标注。

2. 处理多个流程的参数需求：

   • 你已经使用了oneOf注解来指定不同的参数类型，这是正确的做法。
   • 在@Operation注解中，你可以使用description属性来描述每个流程的参数需求，这样用户在查看文档时可以更清楚地了解每个流程所需的参数。

3. 避免将多个类型放入一个大类：

   • 你已经通过定义TypeA和TypeB类来避免将所有类型混合在一起，这是一个很好的做法。
   • 考虑为每个类型定义一个单独的类，并在Swagger中使用oneOf注解来展示这些类型。

4. 确保接口文档正确显示参数：

   • 检查@Schema注解的使用是否正确，确保每个参数的描述和类型都被正确标注。
   • 确保@RequestBody注解的content属性中的schema属性正确地引用了oneOf注解。

以下是一些具体的代码改进建议：

import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.enums.SchemaType;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import lombok.Data;

@Data
public class TypeA {
    @Schema(description = "姓名", required = true)
    private String name;

    @Schema(description = "类型：1-普通， 2-中等，3-高级", required = true)
    private Integer type;
    // 此处忽略其他参数
}

@Data
public class TypeB {
    @Schema(description = "姓名", required = true)
    private String name;

    @Schema(description = "类型：a-低速， b-普通，c-高速", required = true)
    private String type;

    @Schema(description = "状态：t-成功，f-失败", required = true)
    private String status;
    // 此处忽略其他参数
}

@RestController
@RequestMapping("/api")
public class TestGroupController {
    @PostMapping("/your-endpoint")
    @Operation(
        summary = "Example endpoint with grouped parameters",
        description = "This endpoint supports two different processes with different parameters. " +
                      "Process 1 requires name and type (1-3). Process 2 requires name, type (a-c), and status (t-f).",
        requestBody = @RequestBody(
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(
                        oneOf = {
                            @Schema(implementation = TypeA.class),
                            @Schema(implementation = TypeB.class)
                        }
                    )
                )
            }
        ),
        responses = {
            @ApiResponse(description = "Successful response", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseMessage.class)))
        }
    )
    public ResponseEntity<ResponseMessage> yourEndpoint(@RequestBody RequestType request) {
        // Your endpoint implementation
        return ResponseEntity.ok(new ResponseMessage("Success"));
    }

    static class ResponseMessage {
        private String message;

        public ResponseMessage(String message) {
            this.message = message;
        }
    }

    static class RequestType {
        private TypeA typeA;
        private TypeB typeB;

        public TypeA getTypeA() {
            return typeA;
        }

        public void setTypeA(TypeA typeA) {
            this.typeA = typeA;
        }

        public TypeB getTypeB() {
            return typeB;
        }

        public void setTypeB(TypeB typeB) {
            this.typeB = typeB;
        }
    }
}

改进点说明：

• @Operation注解的description属性增加了对两个流程的详细描述，这样用户在查看文档时可以更清楚地了解每个流程所需的参数。
• @Schema注解的oneOf属性在@RequestBody注解中正确使用，确保Swagger能够正确识别并展示不同的参数类型。
• RequestType类用于接收不同类型的参数，并通过oneOf注解在Swagger文档中展示，这样可以避免将所有类型混合在一起，同时确保文档的准确性。

这样修改后的代码应该能够满足你的需求，并在Swagger文档中正确显示所需的参数。