Revision history [back]

You can use the "x-ms-examples" extension in your Swagger schema to provide examples of requests and responses that would be accepted by your API. This will help to clarify which parameters are required, optional, and which may be concealed.

For example, you could specify that a certain parameter should be concealed by providing an example that shows a request body with the parameter value replaced by a placeholder, such as "*". This would indicate to clients that the value of this parameter should not be visible in the request body.

Here's an example of how this could be done:

paths:
  /example:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parameter1:
                  type: string
                parameter2:
                  type: string
                  example: "*****"
                  x-ms-examples:
                    mask:
                      value:
                        parameter1: "value1"
                        parameter2: "value2"
                    unmask:
                      value:
                        parameter1: "value1"
                        parameter2: "value2"

In this example, the "parameter2" property is specified to be concealed, as indicated by the "example" and "x-ms-examples" properties. This would allow clients to make requests without revealing sensitive parameter values in the request body.