How to hide a parameter in swagger?

Question

did anyone succeed to hide a parameter from generated documentation? I found an issue here, but using @ApiParam(access="internal", required=false) before @HeaderParam did not seem to work.

Thacker

Answer 1

Hope this helps.

For Fields

@ApiModelProperty(required = false, hidden = true)
private String hiddenProperty

For Apis

@ApiIgnore
public class MyApi {}

For Parameters

public void getApi(@ApiIgnore String param){}

@ApiModelProperty(hidden="true")
public String paramInsideClass

Spam

Answer 2

If you are using io.swagger.v3, you should use @Parameter(hidden = true) as described on the migration guide here https://springdoc.org/migrating-from-springfox.html

Acquiesce

how to pass there ${some.property} value ? developers have to change contract from boolean to string for corresponding annotation property? – Fat

Answer 3

Ok, looking at the unit tests helped. First you need to define a filter:

import com.wordnik.swagger.core.filter.SwaggerSpecFilter
import com.wordnik.swagger.model.{Parameter, ApiDescription, Operation}
import java.util

class MySwaggerSpecFilter extends SwaggerSpecFilter{
  override def isOperationAllowed(operation: Operation, api: ApiDescription, params: util.Map[String, util.List[String]], cookies: util.Map[String, String], headers: util.Map[String, util.List[String]]): Boolean = true

  override def isParamAllowed(parameter: Parameter, operation: Operation, api: ApiDescription, params: util.Map[String, util.List[String]], cookies: util.Map[String, String], headers: util.Map[String, util.List[String]]): Boolean = {
    if(parameter.paramAccess == Some("internal")) false
    else true
  }
}

And then enable it in web.xml

    <servlet>
        <servlet-name>DefaultJaxrsConfig</servlet-name>
        <servlet-class>com.wordnik.swagger.jaxrs.config.DefaultJaxrsConfig</servlet-class>
        ...
        <init-param>
            <param-name>swagger.filter</param-name>
            <param-value>com.example.MySwaggerSpecFilter</param-value>
        </init-param>
    </servlet>

Thacker

Answer 4

With swagger-springmvc (https://github.com/springfox/springfox) at the moment there's no way to use SwaggerSpecFilter. But it respects @ApiIgnore annotation - it can be applied to method parameter which shouldn't appear in generated metadata.

Scup

Answer 5

Annotation @ApiParam(hidden = true) resolved issue for me.

def myFunc(@ApiParam(hidden = true) i: Int) = {...}

Thrift

doesnt exist. at least not in 1.5.0 – Southward

Answer 6

You could annotate your fields with:

@Schema(description = "foo bar.", required = false, hidden = true, example = "bar")
private String fooDtoField

Glower

Answer 7

In sprigfox-swagger2 implementation there is an annotation @ApiModelProperty that does this.

Example:

@ApiModelProperty(required = false, hidden = true)
private String internallyUsedProperty;

Sosna

Answer 8

This answer describes the current solution in springfox using .ignoredParameterTypes or @ApiIgnore

Pressman

Answer 9

You can use the readOnly and writeOnly keywords to mark specific properties as read-only or write-only. This is useful, for example, when GET returns more properties than used in POST – you can use the same schema in both GET and POST and mark the extra properties as readOnly. readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses.

type: object
properties:
  id:
    # Returned by GET, not used in POST/PUT/PATCH
    type: integer
    readOnly: true
  username:
    type: string
  password:
    # Used in POST/PUT/PATCH, not returned by GET
    type: string
    writeOnly: true

If a readOnly or writeOnly property is included in the required list, required affects just the relevant scope – responses only or requests only. That is, read-only required properties apply to responses only, and write-only required properties – to requests only.

https://swagger.io/docs/specification/data-models/data-types/

Hicks

Answer 10

In case of Java Microprofile OpenAPI you use @Parameter(hidden = true) like this:

import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
...
public Properties getProps(@Parameter(hidden = true) @HeaderParam("X-Access-Key") String accessKey)

Ommatidium