Swagger (OpenAPI 3.0) 仅在 Post 上隐藏字段，而不是 Put 上

Question

我想在我的 REST API 中实现 2 个端点：

@PostMapping("/example")
public ObjectResponse postObject(@RequestBody Example example){... //Add new Example to DB}

@PutMapping("/example")
public ObjectResponse postObject(@RequestBody Example example){...//Update existing Example}

我的示例可能如下所示：

public class Example{
   @Id
   @Hidden
   private String id;
   private String somethingCool;
}

我想隐藏ID，这样使用Post的用户就不会向我发送带有ID的请求。我想让它由我的 mongoDB 生成。

在另一个用例中，在 Put 期间必须发送 ID 以便识别应更新的对象。但我的 Swagger 3.0 上的 ID 字段也隐藏在这里。

如何在我的帖子中隐藏它，但在我的看跌期权中显示它？

非常感谢！

Answer 1

通常这是通过架构和路径参数的组合来完成的。 然后，您可以将 id 属性标记为

readOnly

，并允许用户通过路径参数指定要更新的对象。 看一下这个例子。 请随意复制它并将其粘贴到 swagger 编辑器 中也可以使用它。

openapi: 3.0.4
info:
  title: User With ReadOnly ID
  description: demoing readOnly propertyuser id in pat for put operation as r
  version: 1.0.17
servers:
  - url: /api/v1
paths:
  /user:
    post:
      tags:
        - user
      summary: Create user
      description: This can only be done by the logged in user.
      operationId: createUser
      requestBody:
        description: Created user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        default:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
  /user/{user-id}:
    get:
      tags:
        - user
      summary: Get user by user id
      description: ''
      operationId: getUserById
      parameters:
        - name: user-id
          in: path
          description: 'The name that needs to be fetched. Use user1 for testing. '
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid user id supplied
        '404':
          description: User not found
    put:
      tags:
        - user
      summary: Update user
      description: This can only be done by the logged in user.
      operationId: updateUser
      parameters:
        - name: user-id
          in: path
          description: id that needs to be deleted
          required: true
          schema:
            type: string
      requestBody:
        description: Update an existent user
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
          application/xml:
            schema:
              $ref: '#/components/schemas/User'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        default:
          description: successful operation
    delete:
      tags:
        - user
      summary: Delete user
      description: This can only be done by the logged in user.
      operationId: deleteUser
      parameters:
        - name: user-id
          in: path
          description: The id that needs to be deleted
          required: true
          schema:
            type: string
      responses:
        '400':
          description: Invalid user id supplied
        '404':
          description: User not found
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 10
          readOnly: true
        username:
          type: string
          example: theUser
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: James
        email:
          type: string
          example: [email protected]
        password:
          type: string
          example: '12345'
        phone:
          type: string
          example: '12345'
        userStatus:
          type: integer
          description: User Status
          format: int32
          example: 1
      xml:
        name: user

这里，通过将 id 标记为 readOnly，对于请求对象，它不会显示在 UI 中，例如这个 post 请求：

但是，在get请求中，我们可以清楚地看到该id存在于schema中：

Answer 2

我的解决方案是基于添加带有标记的类并使用 @JsonView 注释。更多详情这里

Answer 3

@tbatch：您将其设置为 POST 和 PUT 只读。我在这里没有看到有效的解决方案。此外，这不应该通过手动干预 OpenApi 定义文件来完成。

@valeriy-emelyanov：@JsonView 的问题在于它创建了模式变体来支持多个视图，这在阅读 OpenApi 文档时让最终用户感到困惑。