标签: springdoc

我有一个 Spring Boot (kotlin) 项目，我使用 springdoc-openapi 来生成 OpenApi 3 规范。我的数据模型如下所示：

open class Animal
data class Cat(val catName: String) : Animal()
data class Dog(val dogName: String) : Animal()

open class Food<T : Animal>
class CatFood : Food<Cat>()
class DogFood : Food<Dog>()

和一个像这样的简单控制器：

@GetMapping("/test")
fun test(): Food<out Animal> = DogFood()

生成的 yaml 是：

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
- url: http://localhost:8085
paths:
  /test:
    get:
      tags:
      - test-controller
      operationId: test
      responses:
        "200":
          description: default response
          content:
            '*/*':
              schema:
                $ref: …

使用 Open API 3 时如何设置自定义标头？我正在使用 Spring Boot + springdoc-openapi-ui 示例。在此示例中，我希望在请求中传递不同的标头。以下配置不显示选择客户标题的选项。

我还需要改变什么？

@Bean
public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) {
 return new OpenAPI()
      .components(new Components().addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
      .addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1")).addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema())))
      .info(new Info()
      .title("Petstore API")
      .version(appVersion)
      .description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
      .termsOfService("http://swagger.io/terms/")
      .license(new License().name("Apache 2.0").url("http://springdoc.org")));
}

我想通过 Intellj 的View->Quick Documentation功能查看 Spring 文档。为了实现这一点，我使用外部文档链接尝试了以下操作：

好的，我已经添加了 Spring Framework 文档的 url。按照指示，但是，当我对 Spring Framework 项目执行 ctrl+Q 时，它没有显示任何文档。在上面的弹出窗口中...

这是我使用的网址：https : //docs.spring.io/spring-framework/docs/current/javadoc-api/

Intellij 支持

但它不起作用。

请问有人可以帮忙吗？

我的 springboot 应用程序有一个 @RestController ，它采用 POJO 类作为参数。

@GetMapping(path="/")
public void sayHello(Person person) {
    System.out.println(person);
}

这是 Person 类的定义，它只是一个 POJO。

public class Person {

private String firstName;
private String lastName;
private int age;

public String getFirstName() {
    return firstName;
}
public void setFirstName(String firstName) {
    this.firstName = firstName;
}
public String getLastName() {
    return lastName;
}
public void setLastName(String lastName) {
    this.lastName = lastName;
}
public int getAge() {
    return age;
}
public void setAge(int age) {
    this.age = age;
} …

这有点奇怪。springdoc-openapi-ui v1.2.32，生成的文档仅包含控制器内的一些映射。

例子：

    @Operation(
            summary = "Foo",
            description = "Foo"
    )
    @PostMapping(path="/v1/foo")
    public ResponseEntity<ResponseObject> postFoo(@RequestBody FooRequestObject searchRequest, HttpServletRequest request){ ... }


    @Operation(
            summary = "Bar",
            description = "Bar"
    )
    @GetMapping(path="/v1")
    public ResponseEntity<ResponseObject> getBar(@RequestBody BarRequestObject request, HttpServletRequest request){ ... }


    @Operation(
            summary = "Bar",
            description = "Bar"
    )
    @PostMapping(path="/v1")
    public ResponseEntity<ResponseObject> postBar(@RequestBody BarRequestObject request, HttpServletRequest request){ ... }

postBar仅针对和服务生成文档getBar，其他路径将被忽略。

我尝试过的：

1. 最初这两个 POST 方法都被命名为post. 我重命名是为了避免冲突。
2. 我没有设置控制器级别路径。
3. 检查注释导入
4. 未命中文档的缓存版本

如果我向控制器添加另一个服务（带或不带注释标记），它也不会显示在生成的 Swagger 中。例如：

@GetMapping(path="/test")
public String getTest(){
    return "test"; …

所以我有一个嵌套模型结构，看起来像这样：

public class TagArea {
    private List<TagGroup> groups;
    
    ... constructors, getters, setters, etc.
}


public class TagGroup {
    private String tagName;
    private List<TagGroup> subgroups;
    
    ... constructors, getters, setters, etc.
}

以及返回所述模型的控制器。但是，生成的 swagger.json 的架构部分如下所示：

{ "components": 
  { "schemas": {
    "TaxonomyClientMetadata": {
      "type": "object", "properties": {
        "tagGroups": {"type": "array", "items": {"$ref": "#/components/schemas/TagGroup"}}
      }
    }, 
    "TagGroup": {
      "type": "object", "properties": {
        "tagName": {"type": "string"}
      }
    }
  }
}

整个财产就这样……消失了。我希望该TagGroup对象看起来更像这样：

"TagGroup": {
  "type": "object", "properties": {
    "tagName": {"type": "string"},
    "subgroups": {"type": "array", …

我使用的主要是springdoc带有spring-boot注释的配置。

我想公开一个未被任何服务引用的特定类模式。是否有可能做到这一点？

在伪代码中，我实际上正在尝试这样做：

GroupedOpenAPI.parseAndAddClass(Class<?> clazz);

或者

GroupedOpenAPI.scan("my.models.package");

===更新===

我设法使用解析架构ModelConverters.getInstance().readAll(MyClass.class);

然后尝试将其添加为OpenApiCustomiser，但它在 UI 中仍然不可见。

我正在使用 SpringBoot 并具有以下依赖项

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.5.12</version>
    </dependency>

Run Code Online (Sandbox Code Playgroud)

控制器类（@RestController）有一个入口点（@GetMapping），该入口点应返回对象的列表：MyClass.java。我在方法上方添加了 Swagger 注释，以便通过 swagger UI 页面创建 API 文档。

swagger文档应该表明返回对象的类型

列表<我的班级>

但我该怎么做呢？如果我做

“@Schema(实现 = List<MyClass>.class)”

出现编译错误。

招摇注解：

@Operation(....)
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "successful operation",
                content = { @Content(mediaType = "application/json",
                        schema = @Schema(implementation = ????)) }),
        @ApiResponse(...),
        @ApiResponse(...)

@GetMapping(value = "/aaa", produces = MediaType.APPLICATION_JSON_VALUE)
public List<MyClass> getAaa(...)
{
    return ...
}

Run Code Online (Sandbox Code Playgroud)

我正在研究Spring Boot v2.2.2.RELEASE and SpringDoc UI and Open API Specification OAS3，我在这里发现了非常相关的问题：https ://github.com/springdoc/springdoc-openapi/issues/201 。

我有 4 个配置文件，分别是 Dev、Stage、UAT 和 Prod，并表示我有 Student API、Employee API 和 Department API。

我想要 UAT 和 Prod 配置文件，我想隐藏 Department API。怎能不呢？

我有一个依赖于 springdoc-openapi 的 spring boot 应用程序（2.5.6）。但是，启动 swagger-ui (http://localhost:8080/v1/swagger-ui/index.html) 不起作用。调试日志表明index.html 不存在。找不到index.html 的原因可能是什么？

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.8</version>
</dependency>

应用程序.yaml

springdoc:
  swagger-ui:
    tagsSorter: alpha
    operations-sorter: alpha
    doc-expansion: none
    disable-swagger-default-url: true

logging:
  level:
    root: DEBUG

server:
  port: 8080

spring:
  application:
    name: fe-applic-app
    api-version: "v1"