标签: openapi

我需要描述一个 api，它在请求正文中包含一个具有必填字段的对象，其中一个字段是一个对象，它本身具有另一组必填字段。

我正在使用 open api v3 和 swagger 编辑器 ( https://editor.swagger.io/ ) 在我将 .yaml 文件放到编辑器上之后，我生成了一个 html 客户端（> 生成客户端 > html）。然后我打开在 .zip 文件中生成的静态页面 index.html 获得此架构：

Table of Contents
body
secureoauthservicesv2Nested_nestedobj
body
id
Integer id of nested obj
nestedobj
secureoauthservicesv2Nested_nestedobj
secureoauthservicesv2Nested_nestedobj
nested object
field1 (optional)
String
field2 (optional)
String

我希望 field1 是必需的，而 field2 是可选的，但事实并非如此。

这是我的 .yaml 文件

openapi: 3.0.0
info:
    title: Example API
    description: Example API specification
    version: 0.0.1
servers:
  - url: https://example/api

paths:
  /secure/oauth/services/v2/Nested:
    post:
      summary: Try nested
      description: Used to …

我正在尝试使用 yasg 自定义我的 api 文档 buuild。

首先，我想确定我自己的部分的命名，以及该部分中应包含哪些端点。似乎节的命名是基于不属于最长公共前缀的第一个前缀，例如：

如果我们有 url api/v1/message 和 api/v1/test ，那么这些部分将被命名为 message 和 test。有没有办法让我确定此部分的自定义命名？

而且每个章节的介绍都是空的，如何在这里添加文字呢？

最后但并非最不重要的一点是，Stripe 有这些令人惊叹的部分分隔符，我如何将它们添加到 drf yasg 中。

如何将数组指定为参数？例如,可以为/ people发布字符串username,firstname和lastname,以及数组myArray.

paths:
  /persons:
    post:
      parameters:
        - name: person_what_is_the_purpose_of_this
          in: body
          description: The person to create.
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
              myArray:
                type: array
                  items:
                    properties:
                      myArrayElement:
                        type: string
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

我正在将Java端点框架(2.0.1)用于Java作为我最后一年项目的一部分,到目前为止它已经相对成功.部署到我的appspot.com域时没有任何问题,但是,我在本地部署时遇到了一些问题.

(以下代码块中对my-project-id的任何引用都是我实际的Google云项目ID的别名)

我有一个带注释的@API类的有效openapi描述符(openapi.json),我使用"gcloud service-management deploy openapi.json"将其部署到云端点.该命令成功返回:

Service Configuration [2017-02-23r0] uploaded for service [api.endpoints.<my-project-id>.cloud.goog]

然后我将返回的config_id映射到app.yaml中正确的endpoints_api_service

endpoints_api_service:
  name: api.endpoints.<my-project-id>.cloud.goog
  config_id: 2017-02-23r0

该服务由gcloud cli工具使用"gcloud service-management list"列出

    NAME                                                           TITLE
    storage-component.googleapis.com                 Google Cloud Storage
    api.endpoints.<my-project-id>.cloud.goog         api.endpoints.<my-project-id>.cloud.goog
    etc...

和"gcloud service-management configs list --service api.endpoints.my-project-id.cloud.goog"

CONFIG_ID        SERVICE_NAME
2017-02-23r0     api.endpoints.<my-project-id>.cloud.goog
... other version configs

并且可以在我的appspot.com域上访问(我可以调用端点并收到正确的响应)

我正在尝试使用java的maven appengine插件(mvn appengine:devserver)在localhost上部署我的项目,但是在jetty启动时我遇到了以下异常:

 WARNING: Failed startup of context com.google.appengine.tools.development.DevAppEngineWebAppContext...

com.google.api.config.ServiceConfigException: Failed to fetch default config version for service 'api.endpoints.<my-project-id>.cloud.goog'. No versions exist!
at com.google.api.config.ServiceConfigSupplier.fetchLatestServiceVersion(ServiceConfigSupplier.java:155)
....

部署然后陷入无休止的循环,尝试启动jetty,并被该错误消息,并重新启动等.任何尝试访问localhost:8080导致"503:服务未找到"错误

我假设我的应用程序的本地部署能够访问使用"gcloud service-management deploy"部署的服务配置,就像appspot.com部署一样,但事实并非如此吗？查看ServiceConfigSupplier.getchLatestServiceVersion()的源代码我收集了serviceManagement.services().configs().list(my-service-name).execute().getServiceConfigs()返回一个空列表,但为什么这只是在当地发生？

额外的信息

我的ENDPOINTS_SERVICE_NAME环境变量与'api.endpoints.my-project-id.cloud.goog'匹配

我注意到几天前com.google.api.config有一个更新(1.0.2),它依赖于旧版本的com.google.api.services.servicemanagement(取决于v1-rev14) -1.22.0,最新版本是v1-rev340-1.22.0)我怀疑这是问题,但我想我会提到它,因为它包含与异常相关的类(ServiceManfigSupplier使用ServiceManagement,它正在抛出例外).他们在寻找服务配置的地方可能存在不一致之处？ …

我无法在对象定义中找到货币数据类型的样本,也找不到有关该主题的文档.

我有一个使用方括号的查询参数的端点:

GET /info?sort[name]=1&sort[age]=-1

在这里,name并且age是从我的模型定义的字段名.

如何为这些参数编写OpenAPI(Swagger)定义？

在OpenAPI(Swagger)2.0中,我们可以像这样定义头参数:

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username

但是在OpenAPI 3.0.0中,参数被请求体替换,我找不到定义头参数的方法,这将进一步用于身份验证.

在OpenAPI 3.0.0中定义请求标头的正确方法是什么？

我想结合使用OpenAPI 3规范编写的API规范，该规范当前分为使用相互引用的多个文件$ref。我怎样才能做到这一点？

我正在开发一个 API ASP.Net Core (net6.0)，其中通过请求在请求标头中传递密钥 (X-API-KEY) 和应用程序 id (X-APP-ID) 来实现身份验证。

https://swagger.io/docs/specification/authentication/api-keys/的“多个 API 密钥”部分对此进行了描述

我在 Program.cs 中配置此功能的代码可以在下面找到。

builder.Services.AddSwaggerGen(c =>
{    
    c.AddSecurityDefinition("apiKey", new OpenApiSecurityScheme()
    {
        Description = "API KEY",
        Name = "X-API-KEY",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });

    c.AddSecurityDefinition("appId", new OpenApiSecurityScheme()
    {
        Description = "APP ID",
        Name = "X-APP-ID",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement()
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "apiKey"
                }                
            },
            Array.Empty<string>()
        },
        {
            new …

我有一个 API 的 Swagger 规范，如下所示：

swagger: '2.0'
info:
  title: my-api
  description: My API
  version: v1
schemes:
  - https
produces:
  - application/json
paths:
  /v1/entry/check:
    post:
      ...
  /v1/entry/enter:
    post:
      ...
  /v1/exit/leave:
    post:
      ...
...

正如您所看到的，中的每个路径都paths带有前缀/v1/，因为规范描述了v1API 的版本（您也可以在info.version值中看到）。

我想知道，有没有办法避免重复这个前缀，即隐式地为所有路径添加前缀/v1/？主要是，我想这样做是为了避免任何意外滥用规范，即完全防止添加另一个没有前缀的路径。