标签: openapi

我正在使用 swagger hub 来创建这个 API；但它不支持用户界面中的多个文件，所以我不确定我这样做是否正确

我的目标是拥有以下

item:{Json describe the item}
images[] = images for item posted as an array
titles[] = Parallel array to images that has the title for image
alt_texts[] = Parallel array to images that has the alt text for image

由于它是文件，所以它必须是多部分的；但不确定我是否正确设置了结构。

Swagger/开放 API 代码

post:
  summary: Add a new item to the store
  description: ''
  operationId: addItem
  requestBody:
    content:
      multipart/form-data:
        schema:
          $ref: '#/components/schemas/NewItemWithImage'
    description: Item object that needs to be added to the store …

有swagger-play插件，说支持 Swagger 2.0，但实际上它使用swagger 注释 1.5.x，而不是 2.0，因此不支持 Open Api 3.0。

有没有人设法使用代码优先接口声明将 Open Api 3 与 Play Framework 连接起来？

我试图将显式的 swagger-core 依赖声明为

"io.swagger.core.v3" % "swagger-core" % "2.0.5"

但没有成功，即我在初始化插件时遇到错误：

[error] 1) Error injecting constructor, java.lang.NoClassDefFoundError: Could not initialize class io.swagger.converter.ModelConverters
[error]   at play.modules.swagger.SwaggerPluginImpl.<init>(SwaggerPlugin.scala:35)
[error]   while locating play.modules.swagger.SwaggerPluginImpl
[error]   at play.modules.swagger.SwaggerModule.bindings(SwaggerModule.scala:11):
[error] Binding(interface play.modules.swagger.SwaggerPlugin to ConstructionTarget(class play.modules.swagger.SwaggerPluginImpl) eagerly) (via modules: com.google.inject.util.Modules$OverrideModule -> play.api.inject.guice.GuiceableModuleConversions$$anon$1)
[error]   while locating play.modules.swagger.SwaggerPlugin

我有一个控制器，它请求一个包含 IFormFile 作为其属性之一的模型。对于请求描述，Swagger UI（我使用 Swashbuckle 和 OpenApi 3.0 for .NET Core）将文件属性的类型列出为类型对象。有没有办法让 Swagger UI 表示确切的类型及其 JSON 表示形式来帮助客户端？

请求模型的控制器如下所示。

[HttpPost]
[Consumes("multipart/form-data")
public async Task<IActionResult> CreateSomethingAndUploadFile ([FromForm]RequestModel model)
{
    // do something
}

模型定义如下：

public class AssetCreationModel
{
    [Required}
    public string Filename { get; set; }

    [Required]
    public IFormFile File { get; set; }       
}

我正在尝试swagger codegen在使用 gradle (kotlin) 构建的项目中工作。

我的参考是这里的示例： https: //github.com/int128/gradle-swagger-generator-plugin，它是在Gradle groovy版本中制作的。

现在情况build.gradle.kts如下：

repositories {
    jcenter()
}

plugins {
    java
    id("org.springframework.boot") version "2.1.2.RELEASE"
    id("io.spring.dependency-management") version "1.0.6.RELEASE"
    id("org.hidetake.swagger.generator") version "2.16.0"
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation ("io.swagger:swagger-annotations:1.5.21")
    swaggerCodeGen("io.swagger:swagger-codegen-cli:2.3.1")

    // Use JUnit test framework
    testImplementation ("junit:junit:4.12")
}

swaggerSources {
    petstore {
        inputFile = file('petstore.yaml')
        code {
            language = 'spring'
        }
    }
}

但 IntelliJ 不喜欢谈论 swagger 的台词：

我是 gradle 的新手，所以我不明白我应该做什么。swaggerCodeGen 应该是一个函数吗？这个函数应该在哪里导入？swaggerSources应该从哪里进口？

我正在使用swagger openapi 规范 3.0从我的界面生成 swagger。我有一个接受请求正文的删除方法。但根据RFC7231，DELETE不接受任何请求体。Swagger-request body也说明了这一点。但我的 API 设计为接受 DELETE 操作中的请求正文。在创建 swagger 时是否有任何解决方法，以便 DELETE 操作接受请求正文。目前我从招摇生成中得到的错误是，

Sematic error: DELETE operations cannot have a requestBody

我正在尝试将 OpenAPI 规范中的一个属性设置为必需且可空：如我提供的 C# 中指定的 false。

我正在使用 NSwag v13.1.3 和 NewtonSoft.Json v12.0.2 以及 .Net Core 2.2

我尝试过使用 NewtonSoft.Json 和 NJsonSchema.Annotations 传递各种组合来强制 NotNull 到字段上，但是 nullable : false 在任何组合中似乎都不可能。

我还尝试使用 NSwagStudio 生成与下面相同的代码，但规范中的 nullable 未设置为 false。

using Newtonsoft.Json;

public class Test {

[JsonProperty("test", Required = Required.Always)]
     public string Test { get; set; }

[JsonProperty("testnullable", Required = Required.AllowNull)]
    public string TestNullable { get; set; }

}

我希望这能为 OpenApi 规范提供 nullable : false 和 nullable : true ，但这就是所呈现的：-

"required": [          
      "test",
      "testnullable"
          ],
"properties": { …

OpenApi 规范列出了一系列可以为其设置的字段和值。您可以在此处查看规格。

我想要一组定义这些规范的接口...我已经开始从头开始制作一个接口，到目前为止它看起来像这样：

// Totally incomplete


export interface IEndpointDocs {
    path: string,
    methods: {
        get?: IMethodDocs,
        post?: IMethodDocs
    }
}

export interface IMethodDocs {
    description?: string,
    operationId?: string,
    produces?: Array<
        | "application/json"
        | "application/xml"
        | "text/xml"
        | "text/html"
    >,
    parameters: IMethodParameterDocs[],
}

export interface IMethodParameterDocs {
    name: string,
    in: "query" | "body" | "path",
    description?: string,
    required?: boolean,
    // really, barely started
    type?: "array",
    items: {
        type: "string"
    },
    collectionFormat: "csv"
    format: "int32"
};

当然这已经完成了，那么我在哪里可以找到这些接口呢？

目前我们的项目已经安装了 Symfony 4.3。从那时起我们已经成长，2.7所以可能会有一些遗留垃圾，但总的来说我们的应用程序运行良好。我们有一个为每条路线添加前缀的调味系统（我不知道这是否是一个好主意，但当我们开始支持它时就是这样）。所以链接看起来像这样：

test.me/{flavor}/project/{UUID}

我们使用注释进行路由，因此有一个annotations.yaml：

controllers:
    resource: ../../src/App/Controller/
    type: annotation
    prefix:   /{flavor}/

现在，由于我们想要引入 API 文档，所以我们想要使用这个 php 包：https://github.com/zircote/swagger-php，它允许我们为 API 编写注释，就像我们使用路由一样，并生成一个swagger.json可以分发到我们的关联项目。问题是在编写注释时会弹出此错误：

$:bin/console cache:clear -e dev                                

 // Clearing the cache for the dev environment with debug true                                           


In FileLoader.php line 166:

  [Semantical Error] The annotation "@OA\Schema" in class App\Controller\Api\Model\APIMessage  
   was never imported. Did you maybe forget to add a "use" statement for this annotation? in /config/routes/../../src/Catrobat/Controller/ (which is being imported from "/config/routes/annotations.yaml"). Make sure …

我们对 HTTP API 使用开放 API 规范 (OAS)。我们在微服务/应用程序中使用这些来生成 Swagger UI，但它也非常适合文档和协作。

一些内部消息传递也通过消息代理 (RabbitMQ/AMQP) 异步完成。其他人/公司是否使用某些东西来记录异步消息操作？如果能给集成团队一些像 OAS 这样的东西就好了……

我正在开发一个带有 .NET Core 后端和 React（TS 支持）前端的小型 Web 应用程序。

对于 API 定义/文档，我使用 OpenAPI，但在为客户端生成代码时遇到问题。下面是 yaml 定义的片段（来自 swagger.json），我用它来使用Swagger 编辑器生成客户端界面

crmObiskiPartnerjevResponse:
      type: object
      properties:
        id:
          type: integer
          format: int32
        PoslovniPartner:
          type: integer
          format: int32
          nullable: true
        DatumObiska:
          type: string
          format: date-time
          nullable: true
        NamenObiskaId:
          type: integer
          format: int32
          nullable: true
        Uporabnik:
          type: integer
          format: int32
          nullable: true
        Opomba:
          type: string
          nullable: true
        NamenObiskaNaziv:
          type: string
          nullable: true
        UporabnikNaziv:
          type: string
          nullable: true
        PoslovniPartnerNaziv:
          type: string
          nullable: true
      nullable: true

问题在于，当为打字稿生成客户端代码时，Swagger 编辑器会弄乱属性的命名。在此示例中，它将第一个字母转换为小型大写字母 (PoslovniPartner -> …