标签: openapi

我试图仅使用 OpenApi 及其 maven 插件openapi-generator-maven-plugin生成接口，但它也生成我不想要/不需要的完整服务。

现在我找到了withInterfaces属性，但当设置为 true 时，它​​还会生成 API 服务。因此它会生成我想要的服务，但也会生成我不想要的服务。

这是我的 pom 配置：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>3.3.4</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${openAPIContractsDirectory}/swagger.json</inputSpec>
                <generatorName>typescript-angular</generatorName>
                <output>${openAPIOutputDirectory}</output>
                <configOptions>
                    <ngVersion>7.2.11</ngVersion>
                    <withInterfaces>true</withInterfaces>
                </configOptions>
                <generateApiTests>false</generateApiTests>
                <generateApiDocumentation>false</generateApiDocumentation>
                <generateModelTests>false</generateModelTests>
                <generateModelDocumentation>false</generateModelDocumentation>
                <supportingFilesToGenerate>variables.ts,configuration.ts,encoder.ts</supportingFilesToGenerate>
            </configuration>
        </execution>
    </executions>
</plugin>

我想要的是模型、pom 中描述的一些支持文件，以及API 接口（不是完整的服务）。

有人知道如何做到这一点吗？

我试图实现一个 OpenAPI 定义，其中我将允许值的共享、完整列表定义为枚举，然后在不同位置使用值的子组来显示每种情况下允许哪些值。

使用Swagger.io 上枚举规范的示例，如果我有这样的定义：

paths:
  /products:
    get:
      parameters:
      - in: query
        name: color
        required: true
        schema:
          $ref: '#/components/schemas/Color'
      responses:
        '200':
          description: OK
components:
  schemas:
    Color:
      type: string
      enum:
        - black
        - white
        - red
        - green
        - blue

那么是否可以定义例如两个以颜色作为参数的不同路径，但其中一个仅接受black或white另一个接受所有颜色？

我在 SwaggerHub 注册并使用 OpenAPI 3.0 创建了一个新的 API。在我的 API 中，/tasks路径有 2 个非必需参数，但我无法将它们设置为非必需 - 编辑器显示“不允许的值”错误。

这是我的 API 定义：

openapi: 3.0.0
info:
  description: A Simple IP Address API
  title: VTasks
  version: v1
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/petrogromovo/Vtasks/1.0.0
  - description: SwaggerHub API Auto Mocking
    url: http://hosting.tk

paths:

  /tasks:
    get:
      tags:
        - tasks
      summary: Get paginated / filtered tasks listing
      operationId: tasks
      parameters:
        - name: page
          in: path
          description: The page number …

我已成功从 .yaml open-api 描述符文件生成接口，但是，如问题标题所示，我希望将这些接口的响应类型从 ResponseEntity 更改为我自己的类型。基本上而不是具有此签名的接口：

 ResponseEntity<Void> clearCache();

对于基本上以这种方式实现的方法：

public void clearCache(){ //do something}

我希望生成的界面就像

void clearCache();

对于我自己定义的类来说也是如此，而不是ResponseEntity<MyBook> getBook(String ISBN);我希望它只用作MyBook返回类型，所以它应该看起来像MyBook getBook(String ISBN); 我用于 openapi-generator 插件的当前设置是

        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>4.3.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>my-own-service-be/src/main/resources/api-docs.yaml</inputSpec>
                        <generatorName>spring</generatorName>
                        <additionalProperties>
                             <additionalProperty>skipDefaultInterface=true</additionalProperty>
                            <additionalProperty>interfaceOnly=true</additionalProperty>
                        </additionalProperties>
                        <generateApis>true</generateApis>
                        <apiPackage>controller</apiPackage>
                        <supportingFilesToGenerate>false</supportingFilesToGenerate>
                        <modelPackage>dto</modelPackage>
                        <generateModelTests>false</generateModelTests>
                        <generateApiTests>false</generateApiTests>
                    </configuration>
                </execution>
            </executions>
        </plugin>

我正在开发一个基于服务的应用程序，我正在为其添加openapi基于注释，例如@RequestBody, @Parameter, @Schema在“@Schema我有一个example字段”中，我可以为其提供格式示例模板String。

我已经提供了，example JSON string但 JSON 内容很大，所以我想将其添加到file我的resources文件夹中。但我目前无法加载它。有人可以让我知道如何添加文件中的示例内容而不是字符串吗？

我尝试查找，发现有一个字段externalValue，但我无法理解如何使其工作。以下是文档的链接。

以下是我的代码，它工作得很好：

@Path("/generate")
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RequestBody(description = "InputTemplate body",
        content = @Content(schema = @Schema(implementation = InputTemplate.class, example = "{\n" +
                "  \"names\":[\n" +
                "    \"Batman\",\n" +
                "    \"Superman\",\n" +
                "    \"Ironman\"\n" +
                "  ],\n" +
                "  \"jobs\":[\n" +
                "    \"Fighting\",\n" +
                "    \"Fyling\",\n" +
                "    \"Teching\"\n" +
                "  ]\n" +
                "}"))) …

我正在构建一个 FastAPI 应用程序，其中有很多 Pydantic 模型。尽管应用程序运行良好，但正如预期的那样，OpenAPI (Swagger UI) 文档并未在该Schemas部分下显示所有这些模型的架构。

这是pydantic的内容schemas.py

import socket
from datetime import datetime
from enum import Enum
from typing import Any, Dict, List, Optional, Set, Union

from pydantic import BaseModel, Field, validator
from typing_extensions import Literal

ResponseData = Union[List[Any], Dict[str, Any], BaseModel]


# Not visible in Swagger UI
class PageIn(BaseModel):
    page_size: int = Field(default=100, gt=0)
    num_pages: int = Field(default=1, gt=0, exclude=True)
    start_page: int = Field(default=1, gt=0, exclude=True)

# visible under schemas on Swagger UI
class …

我想构建一个 Maven 模块，使用 来openapi-generator-maven-plugin从两个 openapi 3 规范生成服务器代码和客户端代码。我希望服务器代码使用 Spring boot，因此我有以下设置：

<generatorName>spring</generatorName>
<library>spring-boot</library>

这工作正常，我需要io.swagger.core.v3:swagger-annotationsOAS jakarta.validation:jakarta.validation-api3 注释和验证。

但是，对于客户端代码，我想使用WebClientSpring，我能找到的唯一设置是：

<generatorName>java</generatorName>
<library>webclient</library>

客户端代码生成，但问题是，它需要较旧的io.swagger:swagger-annotations和javax.validation:validation-api.

我想避免拥有不同的库集。是否有使用同一组注释和验证库的服务器和客户端代码生成设置？最好同时使用io.swagger.core.v3:swagger-annotations和jakarta.validation:jakarta.validation-api。

我想用架构或示例扩展“200SuccessDefault”响应。

paths:
  /home:
      ...
      responses:
        200:
          $ref: '#/components/responses/200SuccessDefault'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PieChartElement'
              examples:
                PieChart:
                  $ref: '#/components/examples/PieChart_1'

这种方法会遇到错误，schema和examples字段被忽略：

与 $refs 一起的同级值将被忽略。要将属性添加到 $ref，请将 $ref 包装到 allOf 中，或将额外的属性移动到引用的定义中（如果适用）。

我试过allOf：

paths:
  /home:
      responses:
        200:
          allOf:
            - $ref: '#/components/responses/200SuccessDefault'
            - content:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/PieChartElement'
                  examples:
                    PieChart:
                      $ref: '#/components/examples/PieChart_1'

这种方法会遇到错误：

不应该有额外的属性additionalProperty：allOf
应该有必需的属性'description'missingProperty：description

如何在FastAPI Swagger autodocs中为 API 方法设置自定义排序顺序？

这个问题展示了如何在 Java 中做到这一点。我之前的问题询问如何按“方法”排序，这是受支持的排序方法。我真的很想更进一步，以便我可以确定方法出现的顺序。现在DELETE显示在顶部，但我希望 API 方法的顺序为：GET, POST, PUT, DELETE。

我知道可以在 JavaScript 中实现自定义排序并将该函数提供给operationsSorter，但您不能从swagger_ui_parametersPython 绑定中可用的属性中包含它。有什么方法可以在Python中完成这个任务吗？

from fastapi import FastAPI

app = FastAPI(swagger_ui_parameters={"operationsSorter": "method"})

@app.get("/")
def list_all_components():
    pass

@app.get("/{component_id}")
def get_component(component_id: int):
    pass

@app.post("/")
def create_component():
    pass

@app.put("/{component_id}")
def update_component(component_id: int):
    pass

@app.delete("/{component_id}")
def delete_component(component_id: int):
    pass

我目前正在 Node.js 和 TypeScript 环境中使用 Serverless Stack (SST) 开发无服务器应用程序。我的应用程序涉及连接到 API 网关的 AWS Lambda 函数。我想自动为我的 API 端点生成 OpenAPI 规范。

我一直在研究使用 Tsoa 或 AWS CDK 等工具，但尚未找到将它们与 SST 集成的简单方法。我了解 AWS API Gateway 具有对 OpenAPI 的内置支持，但我不确定如何通过 SST 来利用它。

有谁对如何使用 SST 自动生成 OpenAPI 规范有经验或见解，或者对我可以用来实现这一目标的工具或方法有任何指导吗？