标签: openapi

我正在尝试使用 open api 3 创建一个 swagger 文档，但是当我尝试allOf在参数定义中使用关键字时出现错误

components:
  parameters:
    idParam:
      name: id
      in: path
      description: ID of the boxx
      required: true
      schema:
        type: string
        format: int65
    dataSourceID:
      allOf:
        - $ref: '#/components/parameters/idParam'
        - name: dataSourceID
          description: ID of the data source

components.parameters['dataSourceID'] 处的架构错误

不应该有额外的属性

附加属性：allOf

是否可以重用另一个参数的值？也许以不同的方式？

查看 swagger 文档，特别是我没有找到如何定义 host 和 basePath 属性的注释。知道在哪里设置它们吗？

参考文档： Swagger-2.X---Annotations

这是使用变量生成的 json： petstore.swagger.io/v2/swagger.json

我有点困惑如何使用 Swagger/OpenAPI v2 对文件下载进行建模。以这个小例子为例：

/files/{name}.zip:
  get:
    summary: Returns the requested ZIP file as "file download" i.e. with content-disposition = attachment
    produces:
      - application/zip
    parameters:
      - name: name
        in: path
        required: true
        type: string
    responses:
      200:
        description: OK
        schema:
          type: file      # <- what is it?
        headers:
          Content-Disposition:
            type: string
            description: the value is `attachment; filename="name.zip"`

我使用什么作为响应类型？是type: string&format: binary还是干脆type: file？

我在看https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types和 https://github.com/OAI/OpenAPI-Specification/blob/master/版本/2.0.md#response-object（响应数据类型file）但我不清楚两者有何不同。应该在什么时候使用？

此外，Content-Disposition标题的使用对选择一个或另一个有影响吗？

自我注意，也看了

• https://github.com/OAI/OpenAPI-Specification/issues/430
• https://github.com/OAI/OpenAPI-Specification/issues/50
• https://github.com/swagger-api/swagger-codegen/issues/319#issuecomment-113880278

每当搜索此内容时，我都会找到有关如何指定模式定义的资源的媒体类型的资源，但我看不到有关模式本身的实际媒体类型是什么的答案。

鉴于 HTTP 的工作方式，对我来说，如果我使用 Accept 标头请求正确的内容类型，我的服务器可以适当地响应是有意义的。

因此，如果我请求/products与Accept: application/json我将获得 JSON 格式的产品，但如果我请求openapi-whatever我将获得 OpenAPI 模式。

我想我可能可以使用application/openapi+json或application/openapi+yaml，但在实际规范中我看不到任何有关它的信息。

我不确定我是否真的想使用 Accept 标头来解决这个差异，但我当然想在任何情况下都使用正确的 Content-Type 标头进行响应。

我正在使用 SwaggerHub 和 OpenAPI 3.0.0。我在 SwaggerHub 中有两个 API。

第一个有以下访问链接：https : //app.swaggerhub.com/apis/myapipath/1.0.0并包含一个名为components/schemas/ApiOffer.

在第二个 API 中，我希望该属性offer成为$ref该定义的一个。我用：

components:
  schemas:
    Offerers:
      type: object
      required:
        - offererId
        - overview
      properties:
        offererId:
          $ref: '#/components/schemas/OfferersId'
        overview:
          $ref: '#/components/schemas/OfferersOverview'
        offer:
          $ref: 'https://app.swaggerhub.com/apis/myapipath/1.0.0#/components/schemas/ApiOffer'

但得到以下错误：

“无法解析引用，因为：无法解析指针：文档中不存在 /components/schemas/ApiOffer”

即使/components/schemas/ApiOffer定义存在。

如何更正我的引用以使其指向其他 API？

我正在使用L5 SwaggerfromDarkOnLine使用 OpenApi 原理图生成 Swagger 文档。

使用模式我可以做

@OA\Property(property="certification", type="array", @OA\Items(ref="#/components/schemas/Certification"))

它工作得很好，显示为

"certification": [
    {
      "certification_id": 0,
      "name": "string"
    }
  ],

. 但是它创建了一个带有方括号的数组块，里面有多个对象。

如何使用相同的工作但丢失数组。就像是

@OA\Property(property="certification", type="object", @OA\Items(ref="#/components/schemas/Certification")),

以便删除方括号并仅显示对象。

"certification": {
      "certification_id": 0,
      "name": "string"
 }

我的资源有一个 ID（典型情况）。

它还有一个slug，一个人类可读但仍然是唯一的标识符（主要用于美化 URL）。

创建资源时，此slug是可选的。如果客户端提供了一个，它正在被使用；否则，服务器生成一个。

但是，在读取资源时需要此slug。

openapi: 3.0.2
info:
  title: Person API
  version: 1.0.0

paths: 
  '/persons/{person-slug}':
    get:
      parameters:
        - $ref: '#/components/parameters/PersonSlug'
      responses:
        200:
          description: Information on a person.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SlugRead'
                  - $ref: '#/components/schemas/Person'
    post:
      parameters:
        - $ref: '#/components/parameters/PersonSlug'
      responses:
        200:
          description: Information on a person.
          content:
            application/json:
              schema:
                allOf: …