Swagger (OpenAPI 3.0) Hide field only on Post, not on Put

Question

I want to implement 2 Endpoints in my REST API:

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

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

My Example could look like this:

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

I want to hide the ID, so that the User who uses Post doesnt send me an request with an ID. I want to let it generate by my mongoDB.

On the other useCase, during a Put an ID must be send in order to identify the Object that should be updated. But the ID Field on my Swagger 3.0 is here hidden as well.

How can I hide it on my Post but show it on my Put?

Thanks alot!

Gasparo

Answer 1

Normally this is done via a combination of schema and path parameters. You would then mark your id property as readOnly, and allow the user to specify which object to update via the path parameter. Take a look at this example. Feel free to copy it and paste it into the swagger editor to play around with it as well.

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

Here, by marking the id as readOnly, it is not displayed in the UI for a request object, such as this post request:

However, in the get request, we can clearly see the id exists in the schema:

Uriia

Answer 2

My solution is based on adding a class with markers and using the @JsonView annotation. More details here

Urbanna

Answer 3

@tbatch: You are making it readonly for both POST and PUT. I don't see a valid solution here. Besides, this shouldn't be done by manually meddling with OpenApi definition file.

@valeriy-emelyanov: The problem with @JsonView is that it creates variations of schemas to support multiple views, which confuse end users while reading the OpenApi docs.

Wailful