标签: openapi

如何从 Swagger UI 禁用或隐藏“服务器”下拉列表？

我的 Maven 依赖项是：

<dependency>
  <groupId>org.springdoc</groupId> 
  <artifactId>springdoc-openapi-ui</artifactId> 
  <version>1.6.13</version>
</dependency>

我的公司使用 Open API Spec 来组织内部 API 的文档，并通过 UI 工具（例如 redoc.ly 或 Swagger）呈现它。API 文档作为私有 git 存储库进行管理，永远不会向公众发布。

私有API文档许可

Swagger 为开源项目提供了很好的示例，例如 MIT、GPL、“Apache 2.0”，但私有 API 文档似乎没有涵盖。

https://spec.openapis.org/oas/latest.html#license-object

{
  "name": "Apache 2.0",
  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}

调查

我看到有些人以这种方式指定他们的许可证。

  license:
    - name: unlicensed
    - url: "www.example.com"

问题

私有 API 文档项目的合适许可证是什么？

您通常如何在私有 Open API 文档中表示许可证对象？

对于内部客户端，OpenAPI 客户端代码生成允许 2 个用例：

1. 服务客户端：生成的客户端代码与特定服务的 openAPI 绑定，涵盖该服务的所有 API，并由处理服务代码的同一开发人员控制和维护（根据生成的代码的需要），并且没有代码重复

2. 依赖于使用情况的客户端：每个用例将根据该特定用例使用的端点生成自己的客户端。您获得较小的客户端，仅覆盖正在使用的端点 - 负责维护这些客户端的人员与负责特定用例的人员是同一个人，并且不同生成的客户端之间可能存在代码重复

如果我比较这两个选项，我会看到以下内容：

+-----------------------+------------------------------+------------------------+
| Criteria              | service based clients        | use-case based clients |
+-----------------------+------------------------------+------------------------+
| Ownership             | Service maintainers          | use-case maintainers   |
| Code duplication      | No duplication               | a lot of duplications  |
| Clients sependancy    | Dependancy exists            | No dependancy          |
| Client code stability | When upgrading client        | When updating client   |
| Base url              | Single per client            | Per endpoint (group) …

Gradle 8.1 (Android Studio Giraffe)要求任务之间显式或隐式依赖关系。如果我要生成要由 Android Gradle 插件使用某些 OpenAPI 工具打包的资源，我不明白如何根据 Gradle 提供的提示来增强 Android Gradle 插件拥有的现有 Gradle 任务：

Possible solutions:
  1. Declare task ':app:generateOpenApiFooBar' as an input of ':app:packageDebugResources'.
  2. Declare an explicit dependency on ':app:generateOpenApiFooBar' from ':app:packageDebugResources' using Task#dependsOn.
  3. Declare an explicit dependency on ':app:generateOpenApiFooBar' from ':app:packageDebugResources' using Task#mustRunAfter.

有没有办法访问现有的“packageDebugResources”任务并添加对我的插件的依赖项？类似以下内容（在我尝试过的任何变体中都不起作用）：

tasks.named('packageDebugResources').dependsOn generateOpenApiFooBar

我正在编写Swagger 2.0规范的API基本上是任何JSON值的存储.

我想要一个读取值的路径和一个存储非预定义深度的任何JSON值(null,数字,整数,字符串,对象,数组)的路径.

不幸的是,似乎Swagger 2.0对输入和输出的模式非常严格,并且不允许JSON Schema允许的整套模式.Swagger编辑器不允许使用示例混合值(例如,可以是布尔值或整数的属性)或松散定义的数组(必须严格定义项的类型)和对象.

所以我正在通过定义MixedValue架构来尝试解决方法:

---
swagger: '2.0'
info:
  version: 0.0.1
  title: Data store API
consumes:
- application/json
produces:
- application/json
paths:
  /attributes/{attrId}/value:
    parameters:
    - name: attrId
      in: path
      type: string
      required: true
    get:
      responses:
        '200':
          description: Successful.
          schema:
            $ref: '#/definitions/MixedValue'
    put:
      parameters:
      - name: value
        in: body
        required: true
        schema:
          $ref: '#/definitions/MixedValue'
      responses:
      responses:
        '201':
          description: Successful.
definitions:
  MixedValue:
    type: object
    properties:
      type:
        type: string
        enum:
        - 'null'
        - boolean
        - number
        - integer
        - …

URL上是否存在任何规范或约定swagger.json（或约定的名称），以便可以自动发现我网站的公共API？

我希望在OpenAPI中表示以下JSON对象：

{
  "name": "Bob",
  "age": 4,
  ...
}

属性的数量和属性名称尚未完全确定，因此我希望使用AdditionalProperties。但是，我不太确定如何通过OpenAPI / Swagger 2.0表示它。我尝试了这个：

Person:
  type: object
  additionalProperties:
    type:
      - int
      - string

或等效的JSON：

{
  "Person": {
    "type": "object",
    "additionalProperties": {
      "type": ["int", "string"]
    }
  }
}

但这不太奏效。有什么方法可以保留我要表示的JSON对象的结构，特别是字符串和整数，而不是任意对象类型？

我正在使用CMS。因此，当我转到“ / painter”时，其路由到“ JobController”。/ plumber也被路由到'JobController'。除此之外，它是MVC而不是WebAPI，因此大张旗鼓不会发现它，这是可以理解并且很好的。

但是我有一个用例，如果我访问/ pianter？json = 1，它将返回json而不是HTML。

因此，作为API UI，我们希望公开此“假”端点，以便设计人员可以看到输出模型。

那么，我是否可以添加一个完全伪造的终结点-仅在招摇的UI中在设计人员和开发人员之间只有一个用户界面？

除了具有可视化的UI外，我们还希望基于openapi标准生成一些TypeScript。

使用此架构定义：

schemas:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      - id: 1
        firstName: Sherlock
        lastName: Holmes
      - id: 2
        firstName: John
        lastName: Watson

我得到了预期的结果：

[
  {
     "id": 1,
     "firstName": "Sherlock",
     "lastName": "Holmes"
  },
  {
     "id": 2,
     "firstName": "John",
     "lastName": "Watson"
  }
]

现在，我想为单个用户（ContactModel1）和用户数组（AllContacts）的一部分重用Holmes示例。但是，如果我使用引用的示例：

schemas:

  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      Homes:
        $ref: '#/components/examples/Homes'
      Watson:
        $ref: '#/components/examples/Watson'

  examples:

    Holmes:
      value:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    Watson:
      value:
        id: 2
        first_name: John
        last_name: Watson

我在Swagger UI中得到了这个意外的结果： …

我目前正在将我们的API文档（即Swagger 1.5）迁移到Swagger 2.0（OpenApi 3.0）

API文档是Swagger文档，它使用maven包swagger-annotations和Java注释通过Java注释生成swagger-jaxrs。我已经用新版本更新了pom.xml，因此它看起来像：

        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>2.0.6</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2</artifactId>
            <version>2.0.6</version>
        </dependency>

并且所有旧注释都被新注释替换（变化很大）并且看起来不错。

关键是我们使用BeanConfig来定义文档的常规配置并自动扫描所有REST资源，因此文档是在自动生成的/swagger.json。

该问题是我无法找到做这样的事情，创建使一切变得在产生BeanConfig和自动扫描资源的“新路” /swagger.json或/openapi.json（也许现在是一样的东西OpenAPIDefinition？）

如果有人能指出我正确的方向，我将不胜感激。