CODEWITHSUNDEEP
scalarestswagger
eugen-fried
eugen-fried

Reputation: 2173

How to hide a parameter in swagger?

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.

Upvotes: 26

Views: 82445

Answers (10)

Gas
Gas

Reputation: 18040

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)

Upvotes: 1

Serhii Smirnov
Serhii Smirnov

Reputation: 1357

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/

Upvotes: 0

Oweis Al-Agtash
Oweis Al-Agtash

Reputation: 188

You could annotate your fields with:

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

Upvotes: 3

Bond
Bond

Reputation: 131

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

Upvotes: 13

Vasyl Yamnych
Vasyl Yamnych

Reputation: 41

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

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

Upvotes: 3

Ronny Shibley
Ronny Shibley

Reputation: 2155

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

Upvotes: 28

gogstad
gogstad

Reputation: 3739

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

Upvotes: 0

magiccrafter
magiccrafter

Reputation: 5484

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

Example:

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

Upvotes: 1

Paul Lysak
Paul Lysak

Reputation: 1294

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.

Upvotes: 4

eugen-fried
eugen-fried

Reputation: 2173

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>

Upvotes: 8

Related Questions