标签: openapi

我在 azure 函数中定义了一个 api，我想以可以生成 openAPI 规范的方式对其进行注释。

我尝试过使用 tsoa，但它似乎与无服务器不兼容。目前，openAPI 规范是使用 swagger-jsdoc 生成的，但在注释中包含描述符是不可维护的。我想要类似于 .NET 端 swagger 的工作方式，其中我可以使用路由信息注释函数，并且库将生成 openAPI 规范。这对于打字稿存在吗？我还查看了 Azure 的 API 管理来生成规范，但这些函数目前不是函数应用程序的一部分（它们作为静态站点 api 的一部分部署），并且我不确定 api 管理是否能够处理打字稿类型。

这是我当前使用 swagger-jsdoc 定义规范的设置示例。

/**
 * @swagger
 *  /api/user:
 *    get:
 *      tags:
 *      - user
 *      summary: Get the user by Id
 *      description: "Returns a single user"
 *      parameters:
 *      - in: "query"
 *        name: "id"
 *        description: "ID of the user to return"
 *        required: true
 *        schema:
 *          type: "string"
 *      responses: …

我有一个 Springboot Rest 应用程序，其中有自动转换 API 和参数的注释。

我有自定义注释，其中包含一些注释，如何将其生成到 OpenAPI 3 中的 swagger 页面？

Ex:
@RestController
Class Controller {

@GetMapping(/test/result/)
@CustomAnnotation(value = "This description should come in swagger")
void method() {
}
}

我想描述返回未知/任何类型的 JSON 对象的 OpenAPI。

如果我在下面的 yaml 中定义返回类型，我仍然会看到生成的客户端仅返回原始字符串。

responses:
  200:
    description: Returns any JSON object
    schema:
      type: string
      format: object

有没有办法将返回类型描述为 JSON 对象而不描述其架构？

我有一个 API，它接受查询参数作为对象。我正在使用它添加多个过滤器来过滤结果。

当我收到来自 swagger 的请求时，控制器中的过滤器对象为 null。

userFilter是 POJO 类。它被用作 aquery param并且在控制器中，它作为 null 出现。

在swagger上，显示如下

userFilter当尝试从 userFilter 访问任何字段时，对象未构造并在控制器类中获取 NullPointerException。

我正在使用 drf-spectaulous 为 django 生成 OpenAPI 模式。由于我没有使用序列化器，因此我在extend_schema装饰器中定义所有内容。现在我的问题是，是否可以手动定义组件模式。

这是我的 api 视图的示例：

from rest_framework.decorators import api_view
from drf_spectacular.utils import (extend_schema, OpenApiExample)
from drf_spectacular.types import OpenApiTypes
from rest_framework.response import Response

@extend_schema(
    examples=[OpenApiExample(
        value=[
            {'title': 'A title'},
            {'title': 'Another title'},
        ],
    )],
    responses={
       200: OpenApiTypes.OBJECT
    }
)
@api_view(['GET'])
def list_articles(request):
    return Response([{'title': 'Test1'}, {'title': 'Test2'}])

并且相应的组件显示为空（例如在 swagger 中）：

这是文档中的定义，但我无法弄清楚如何使用 drf-spectaulous 来实现它。

使用 FastAPI，如何在 OpenAPI (Swagger) 文档上的请求标头上将字符集添加到内容类型（媒体类型）？

@app.post("/")
def post_hello(username: str = Form(...)):
   return {"Hello": username}

OpenAPI (http:///docs) 显示“ application/x-www-form-urlencoded ”。

我尝试改变如下：

def post_hello(username: str = Form(..., media_type="application/x-www-form-urlencoded; charset=cp932")):
   return {"Hello": "World!", "userName": username}

但不能添加charset=cp932

我想根据请求将“ application/x-www-form-urlencoded; charset=cp932 ”设置为 Content-Type 。我想获得由字符集解码的用户名。

我在版本 5.3.1 中使用插件 openapi-generator-maven-plugin。

将 openapi 规范从 3.0.3 升级到 3.1.0 会导致生成阶段错误：

规格样本：

{
  "openapi": "3.1.0",
  "info": {
    "title": "Spec sample",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "responses": {
          "200": {}
        }
      }
    }
  }
}

插件错误：

[INFO] Output directory ((removed)\target\generated-sources\openapi) does not exist, or is inaccessible. No file (.openapi-generator-igno
re) will be evaluated.
[WARNING] (removed).json [0:0]: unexpected error in Open-API generation
java.lang.RuntimeException: Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.
    at org.openapitools.codegen.DefaultGenerator.generate …

我试图在 swagger (OAS3) 中指定以下 requestBody：

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "user@example.com",
  "interest_ids": [
     1,2
  ]
}

我目前已指定 requestBody 如下：

 *     @OA\RequestBody(
 *          required=true,
 *          @OA\JsonContent(
 *              required={"email"},
 *              @OA\Property(property="first_name", type="string", format="string", example="John"),
 *              @OA\Property(property="last_name", type="string", format="string", example="Doe"),
 *              @OA\Property(property="email", type="string", format="email", example="user@example.com"),
 *              @OA\Property(property="interest_ids", type="array", @OA\Items(
 *                      type="integer",
 *                      example=3
 *                  ),
 *              ),
 *          ),
 *     ),

这给了我一个正确的 requestBody，但是这显然只给了我一个键，其值3作为interest_ids数组的示例值。如何在不将类型设置为字符串的情况下指定多个 id？我尝试了多种解决方案，例如将示例设置为example={1,2}，不幸的是，这给了我数组中的另一个数组interest_ids：

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "user@example.com",
  "interest_ids": [
    [ …

我刚刚进入 api 文档并尝试使用 Swagger

这是我的 php 文件，其中包含我想要记录的路由：

<?php

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
return [
    /**
     * @OA\Get(
     *     path="/api/v1/test",
     *     @OA\Response(response="200", description="An example resource")
     * )
     */
    'GET api/v1/test' => 'test/index',
];

但是当我运行./vendor/bin/openapi api/config/routes.phpcli 时只输出错误：

Warning: Required @OA\Info() not found
Warning: Required @OA\PathItem() not found
openapi: 3.0.0

然后我尝试了 Swagger2，效果很好

我使用dockerphp8.1镜像php:8.1-fpm-alpine、最新的zircote/swagger-php软件包和 Yii2 框架

我目前有

openapi: 3.1.0
info:
  title: My API
  version:
    $ref: package.json#/version
  description: |
    practically the same content as README.md

有没有办法使用 JSON 指针嵌入文本而不是 JSON 对象？类似的东西

openapi: 3.1.0
info:
  title: My API
  version:
    $ref: package.json#/version
  description: |
    $ref: README.md