标签: openapi

definitionsSwagger 2.0中的全局部分和部分有什么区别components？

我遇到了一个 Swagger 定义 YAML 文件，该文件标记为swagger: '2.0'. 它有一个名为definitions下面的部分parameters。这类似于
https://swagger.io/docs/specification/2-0/basic-struct/
的“输入和输出模型”部分中描述的内容。

此外，在文件的更下方，它还包含下面的部分components。这与https://swagger.io/docs/specification/components/schemas中描述的类似， 这看起来像 OAS3。

但是，这个特定的 YAML 文件具有两个部分。我不确定是否definitions适用于 Swagger 2.0 和components是否schemas适用于 OAS 3.0。是这样吗？

和 可以definitions在components同一类型的 YAML 文件中使用吗swagger: '2.0'？或者我们应该坚持使用definitionsor 吗components？

# definitions section looks like this
definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
    # Both properties are required
    required:  
      - …

我希望 OpenAPI 生成器（https://github.com/OpenAPITools/openapi-generator）能够根据 Spring Boot Data 中的实现在 API 中生成 Pageable 参数。我一直在尝试寻找一种合适的开箱即用的解决方案，但找不到。

理想情况下，此 Pageable 参数应仅按以下方式添加到 GET 方法：

default ResponseEntity<User> getUser(@ApiParam(value = "value",required=true) @PathVariable("id") Long id, **Pageable pageable**)

因此，在我的控制器中实现此接口后，我需要重写它并具有上述的 Pageable 参数。我不想有单独的大小或页面参数，这里只有这个可分页。

感谢您的任何提示和帮助！

我有一个 Django REST Framework 项目，它使用ModelViewSet为包含FileField.

我在这里分享了演示此问题的 Django 项目的完整示例。但总结一下关键组成部分：

模型.py

from django.db import models


class Profile(models.Model):
    image = models.FileField(upload_to='uploads/%Y/%m/%d/')

视图.py

from rest_framework import (
    viewsets,
    serializers,
    parsers,
)

from sample import models


class ProfileSerializer(serializers.ModelSerializer):

    class Meta:
        model = models.Profile
        fields = ['id', 'image']
        read_only_fields = ['id']


class ProfileViewSet(viewsets.ModelViewSet):
    serializer_class = ProfileSerializer
    queryset = models.Profile.objects.all()

urls.py

from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerView,
)

from django.contrib import admin
from django.urls import path, include
from django.conf.urls.static import static
from …

目前我正在使用 quarkus 开发一个应用程序。我有一个描述一切的 openapi yaml 文件。我想知道是否有 quarkus 扩展或工具可以用来生成可以生成和使用相同文件格式的其余端点。

在 openapis.org OpenAPI 3.0( https://spec.openapis.org/oas/v3.1.0 ) 中，我无法找到maxLength关键字来表示数据类型或替代数据类型允许的最大长度。谁能帮忙，我需要用x-来做吗？

所以基本上我有一个 VS Code 扩展，它提供基于内置 JSON 验证器的JSON 文件验证。我正在验证的模式（OpenAPI 3.1.x）使用​​元模式功能，即$dynamicRef，我也需要使用它，因为我引用了 OpenAPI 模式。

当定义如下所示的自定义架构时，我收到一条警告，指出验证器尚不支持元架构功能。不用说，验证确实不起作用。当使用正常时$ref，大多数架构都可以工作，但使用的属性却不起作用$dynamicRef。$dynamicRef所以我也被迫引用架构。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "OpenApiPathObject",
  "type": "object",
  "additionalProperties": {
    "$dynamicRef": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json#/$defs/path-item-or-reference"
  }
}

The schema uses meta-schema features ($dynamicRef) that are not yet supported by the validator.

我使用的是 VS Code 1.69.0，并将扩展所需的引擎更改为 ^1.68.0，其中应包括对架构版本的支持，如2022 年 5 月发行说明Draft 2020-12中所述。我有什么选择以及如何解决此警告？

这是扩展的摘录package.json

The schema uses meta-schema features ($dynamicRef) that are not yet supported by the validator.

当我使用 NSwag 为 API 生成 C# 客户端时，其中 API 包括可用于多种 Http 请求类型（例如 POST、GET）的端点，客户端为每个具有相同基本名称的请求生成一个方法，并加上一个数字。

例如使用这个 API：https : //api.premiumfunding.net.au/assets/scripts/swagger/v1/swagger.json

该架构包含一个端点/contract支持GET和POST要求，以及端点/contract/{ID}支持GET，POST并DELETE请求。

生成的客户端有方法：

• ContractAsync 对于没有 ID 的 GET 请求
• Contract2Async 对于没有 ID 的 POST 请求
• Contract3Async 对于带有 ID 的 GET 请求
• Contract4Async 用于带有 ID 的 POST 请求
• Contract5Async 用于带有 ID 的 DELETE 请求

我希望它生成名为的方法：

• GetContractAsync 对于没有 ID 的 GET 请求
• PostContractAsync 对于没有 ID 的 POST 请求
• GetContractAsync 对于带有 ID 的 …

使用JSON Schema和Open API规范(OAS)来记录REST API时,如何定义UUID属性？

我在Express 中使用swagger-jsdoc。使用这个库来描述一个 api 端点，我在 YAML 的 JSDock 块中使用以下几行：

/**
 * @swagger
 * /users:
 *    post:
 *      summary: Register a user
 *      tags: [Users]
 *      description: Register a new user and return its cookie token (connect.sid)
 *      parameters:
 *        - in: body
 *          name: body
 *          schema:
 *            type: object
 *            required: [login, password, confirm]
 *            description: user's credential
 *            properties:
 *              login:
 *                type: string
 *                minLength: 3
 *                maxLength: 10
 *              email:
 *                type: string
 *              password: …

我正在运行 springdoc-openapi-maven-plugin，具有以下（标准）配置：

        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>0.2</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

该插件似乎运行，但没有输出。

我在 Maven 输出中收到 404 错误：

[INFO] --- springdoc-openapi-maven-plugin:0.2:generate (integration-test) @ paatinc-util-websrv ---
10:40:33.930 [http-nio-8080-exec-1] INFO  o.a.c.c.C.[Tomcat].[localhost].[/] - Initializing Spring DispatcherServlet 'dispatcherServlet'
10:40:33.931 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Initializing Servlet 'dispatcherServlet'
10:40:33.956 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Completed initialization in 25 ms
10:40:33.969 [http-nio-8080-exec-1] INFO  io.paat.util.filter.LoggingFilter - GET http://localhost:8080/v3/api-docs from 127.0.0.1
[ERROR] An error has occured: Response code 404

我可以从我的日志中看到 404 正在调用：http://localhost:8080/v3/api-docs

我还在 springdoc-openapi-maven-plugin 文档中看到以下配置：

 <configuration> …