标签: openapi

我有两个模式对象：

'#/components/schemas/customer' '#/components/schemas/account'

有没有办法我们可以使用开放 API 3.0 规范使用 '#/components/schemas/customer' 和 '#/components/schemas/account' 定义发布响应正文

我正在使用 Spring Boot + Spring Rest Pagination + Open API 3。

@Operation(summary = "Find Contacts by name", description = "Name search by %name% format", tags = { "contact" })
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Contact.class)))) })

@Parameter(in = ParameterIn.QUERY, description = "Zero-based page index (0..N)", name = "page"
, content = @Content(schema = @Schema(type = "integer", defaultValue = "0")))
@Parameter(in = ParameterIn.QUERY, description = "The size of …

我根据 DREDD 的规范测试我的 Api（考虑到Dredd 支持的痛苦限制，用 Openapi3 编写）。不，我有一个端点，如果 Accept-header 设置为如此，它会生成 CSV 数据。

    '/my-endpoint':
        summary: ...
        description: ...
        get:
 #          parameters:
 #              - 
 #                  in: header
 #                  name: Accept
 #                  description: "Response format: application/json or text/csv"
 #                  example: "text/csv"
            responses:
                '200':
                    description: ...
                    content:
                        text/csv:
                            schema:
                                type: string
                            example:
                                summary: 'csv table'
                                value: 'cell1, cell2'

当我使用 Dredd 运行测试时，测试失败并显示

expected: 
headers: 

body: 
[
  {
    "key": "summary",
    "value": "csv table"
  },
  {
    "key": "value",
    "value": "cell1, cell2"
  }
]
statusCode: 200

显然存在一些误解，Dredd …

我正在使用 gRPC 服务生成 swagger json 文件protoc-gen-swagger。输出 json 是使用空响应示例生成的，我想将响应示例添加到定义中，以便它自动填充到生成的 json 中。

这是我目前的定义。

service UserService {
  rpc GetUser (GetUserRequest) returns (UserResponse){
    option (google.api.http) = {
      get: "/api/v1/user/{username}"
      response_body: "*"
    };
    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
      description: "Returns user object";
      operation_id: "get_user";
      summary: "Get User";
    };
  }
}

message GetUserRequest {
  string username = 1;
}

message UserResponse {
  User user = 1;
}

message User {
  string first_name = 1;
  string last_name = 2;
  string username = 3;
}

当我使用命令生成 swagger …

我有一个这样的 DTO：

# AppBundle\DTO

/**
 * @OA\Schema(
 *      schema="ProductDto",
 *      type="object",
 *      required={
 *          "foo",
 *          "bar",
 *          "baz",
 *      },
 * )
 */
class ProductDto
{
    /**
     * @OA\Property(description="foo bar baz")
     * @var string|null
     */
    private $foo;

    ...
 }

我试图在我的控制器中引用这个 DTO，但似乎这个文件没有被解析。

# AppBundle\Controller\Api\v1
class ProductController {

  ...

  /**
    * @OA\Post(
    *      @OA\RequestBody(
    *          required=true,
    *          content={
    *              @OA\MediaType(
    *                  mediaType="application/json",
    *                  @OA\Schema(
    *                      type="object",
    *                      ref="#/components/schemas/ProductDto",
    *                  ),
    *              ),
    *          }
    *      ),
    * )
    */
  public function …

我有一个 Spring Boot 应用程序，它从 2 个规范文件生成 2 个 API。我可以swagger-ui通过添加为其中之一生成一个页面

springdoc.swagger-ui.url=/firstAPI.yaml

到application.properties。但是我怎样才能包含第二个 API 呢？

我试过：

springdoc.swagger-ui.urls=/firstAPI.yaml,/secondAPI.yaml

这会创建一个组合http://localhost:8080/v3/api-docs/，但http://localhost:8080/v3/api-docs/尽管可以在顶部栏中的两个规格之间进行选择，但页面显示“无法加载 API 定义”。

我正在开发一个具有以下工作流程的项目：API 网关（使用开放 api 定义）触发来自 AWS 的 Step 函数。有 2 个步骤，如果出现错误，状态机定义中有一个 catch 块。

但我面临错误处理的问题。即使我的代码抛出错误（例如 400），我的 Postman（或其他 REST API 测试工具）也会响应 200。我想要 500/400...

这是代码：

Step 函数定义为无服务器

stepFunctions:
  stateMachines:
    PostPayment:
      name: testfunction
      type: EXPRESS
      definition:
        Comment: 'test'
        StartAt: Function1
        States:
          Function1:
            Type: Task
            Resource: !GetAtt Function1.Arn
            Catch:
              - ErrorEquals: ['HandledError']
                Next: Fallback
            Next: Function2
          Function2:
            Type: Task
            Resource: !GetAtt Function2.Arn
            Catch:
              - ErrorEquals: ['HandledError']
                Next: Fallback
            End: true
          Fallback:
            Type: Fail
            Cause: "Error occured",
            Error: "Error"

这是我的 openapi yml

x-amazon-apigateway-request-validator: all
x-amazon-apigateway-integration:
  requestParameters:
    integration.request.path.id: …

我想将图像添加到 FastAPI 自动文档（由 Swagger UI 提供），但我不知道如何执行此操作。这是代码：

@api.get(path='/carbon-credit/',
    responses={
        200: {'description': 'Ok',
            "content": {
            "image/jpeg": {
                "example": 'https://picsum.photos/seed/picsum/200/300'
                    }
                }},
        404: {"description": "not found"},
        422: {'description': 'not found 2'},
    },
    name='API for Carbon Credit',
    description="get carbon credit",
    tags=['Images'],
    response_class=Response)

正如您从代码中看到的，我尝试使用 URL 来执行此操作，而我在 ReDoc 和 Swagger UI 中得到的只是文本形式的 URL，而不是实际图像。另外，我想使用存储在本地驱动器中的图像。

Swagger UI 和 ReDoc 的屏幕截图：

我怎样才能做到这一点？

提前致谢。

之前在 SpringBoot v2.5.7 中，我有这个 Spring REST 控制器方法。它有一个TestCriteriaDTO 类型作为路径参数。

@GetMapping(path = "/test")
public void test(TestCriteria testCriteria) {

}

而TestCriteria班级就是这样的。(Language是一个可以采用 或EN的枚举FR)。

public class TestCriteria {
    @ApiModelProperty(allowEmptyValue = true)
    List<Language> langauges;
    
}

我使用了 Springfox Swagger (springfox-boot-starter v3)，Swagger UI 如下所示：

但后来我不得不将 SpringBoot 升级到 v3，并使用 Springdoc 和 OpenAPI v3 for Swagger。现在TestCriteria类看起来像这样：

public class TestCriteria {

    @Schema(type="array")
    @Parameter(allowEmptyValue = true)
    List<Langauge> languages;

}

现在 Swagger UI 不再显示languages为可选择值的字段，而是显示为对象。

我还比较了生成的 OpenAPI 定义，发现：

以前的 API …

例外 ：-

jakarta.validation.NoProviderFoundException：无法创建配置，因为找不到 Jakarta Bean 验证提供程序。将 Hibernate Validator (RI) 之类的提供程序添加到您的类路径中。在 jakarta.validation.Validation$GenericBootstrapImpl.configure(Validation.java:291) ~[jakarta.validation-api-3.0.2.jar:na] 在 jakarta.validation.Validation.buildDefaultValidatorFactory(Validation.java:103) ~[ jakarta.validation-api-3.0.2.jar:na] 在 org.hibernate.cfg.beanvalidation.TypeSafeActivator.getValidatorFactory(TypeSafeActivator.java:479) ~[hibernate-core-6.1.6.Final.jar:6.1.6 .Final] 在 org.hibernate.cfg.beanvalidation.TypeSafeActivator.activate(TypeSafeActivator.java:82) ~[hibernate-core-6.1.6.Final.jar:6.1.6.Final] 在......

....org.springframework.boot.SpringApplication.run(SpringApplication.java:308) ~[spring-boot-3.0.2.jar:3.0.2] 在 org.springframework.boot.SpringApplication.run(SpringApplication.java ：1302）〜[spring-boot-3.0.2.jar：3.0.2]在org.springframework.boot.SpringApplication.run（SpringApplication.java：1291）〜[spring-boot-3.0.2.jar：3.0。 2] 在 com.spring.security.MicroServiceServer1Application.main(MicroServiceServer1Application.java:10) ~[classes/:na] 在 java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(本机方法) ~[na:na]在 java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77) ~[na:na] 在 java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[ na:na] 在 java.base/java.lang.reflect.Method.invoke(Method.java:568) ~[na:na] 在 org.springframework.boot.devtools.restart.RestartLauncher.run(RestartLauncher.java: 49) ~[spring-boot-devtools-3.0.2.jar:3.0.2]org.hibernate.cfg.beanvalidation.BeanValidationIntegrator.integrate(BeanValidationIntegrator.java:137)

Maven 依赖关系：-

...
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.0.2</version>
        </dependency>
    
    
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional> …