标签: openapi

使用 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")));
}

我在使用 Open API 3.0.1 java 注释定义readOnly特定方法的属性时遇到一些问题。在操作期间，POSTAPI 需要一个NewAccount模型。这是模型的截断表示；

{
    "user": {
        "id": "...",
        ...
    },
    "account": {
        "id": "...",
        ...
    }
}

我需要的是定义此操作中的user.idand 。我的所有文档都是通过注释从代码生成的，这就是我到目前为止所拥有的；account.idreadOnly

{
    "user": {
        "id": "...",
        ...
    },
    "account": {
        "id": "...",
        ...
    }
}

您能帮我将 Postman 文件转换为 openAPI 3.0 并将它们下载到机器吗？

这必须在 Node.js 中实现，我对它非常陌生。

谢谢。

我正在尝试使用 springdoc-openapi-ui 使用 gradle 依赖项。

梅文

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

摇篮

    plugins {
    id 'org.springframework.boot' version '2.3.1.RELEASE'
    id 'io.spring.dependency-management' version '1.0.9.RELEASE'
    id 'java'
}

group = 'fete.bird'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '14'
compileJava {
    options.compilerArgs += ["--enable-preview"]
}
repositories {
    jcenter()
    mavenCentral()
}
ext {
    set('springCloudVersion', "Hoxton.SR6")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-rest'
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
    }
    implementation 'org.springdoc:springdoc-openapi-ui'
    implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    implementation 'org.springframework.cloud:spring-cloud-starter-config'
    implementation 'org.springframework.kafka:spring-kafka'
    implementation 'org.projectlombok:lombok'
}
dependencyManagement {
    imports …

我正在8000端口上运行 Django 和 Nginx。这里Nginx暴露在8000端口之外。但在 Swagger UI 中，base_url设置为没有端口。因此 Swagger 尝试在没有端口的情况下访问端点，然后它给出的响应为TypeError: Failed to fetch。

请参考下图了解base_url是如何设置的

请参考下图了解 Swagger 是如何发送请求的

当我使用 Postman 访问端点（带有端口）时，它工作正常。仅当我尝试使用 Swagger 时才会出现此问题（因为发送的请求没有端口）。

这里我希望 Swagger 使用该端口发送所有请求。请帮我解决这个问题。谢谢。

笔记：

1. 我正在使用drf-yasg==1.17.1包来生成Swagger UI
2. 其他要求是Django==3.0.3和djangorestframework==3.11.0

我正在尝试为一个项目（用 Laravel 编写）编写 OpenAPI 文档，并在几个 API 点上苦苦挣扎。

一返回

{
    "active_options": {
        "1": {
            "name": "name1",
            "type": "type1"
        },
        "2": {
            "name": "name2",
            "type": "type2"
        },
        "3": {
            "name": "name3",
            "type": "type3"
        }
    },
    "server": {
        "url": "URL...",
        "settings1": "value"
    },
    "message": "Server settings retrieved."
}

我正在努力解决如何使用 l5-swagger 插件编写此注释。“1”、“2”、“3”是可选的，它们的任意组合都有效。

我想使用optionalProperties，但我不知道如何将它们组合在一起。

这是我得到的最接近的：

     *   @OA\Response(
     *     response=200,
     *     description="Settings",
     *     @OA\JsonContent(
     *       @OA\Property(property="options",
     *         @OA\Items(
     *            @OA\Property(property="name", type="string"),
     *            @OA\Property(property="type", type="string")
     *         )
     *       ),
     *     )
     *   ),

但示例生成的是这样的：

{ …

在 OpenAPI/Swagger 文件中声明“char”的正确方法是什么？我尝试过这些..但没有用

myTestProperty:
    type: char
    example: C or B

我也这样累了，但没有运气

myTestProperty:
    type: string
    format: char
    example: C or B

该文档确实特别提到了 char 数据类型，但在其他地方也找不到。

请建议。

这有点奇怪。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 中仍然不可见。