Ignore ApiParam. #167

earaya · 2013-04-03T22:48:53Z

There are several scenarios which may necessitate a parameter to be excluded from the documentation.

This works by adding an "ignore" flag to the ApiParam annotation and then checking for it when creating the documentation.

There are several scenarios, which may necessitate a parameter to be excluded from the documentation. This works by adding an ignore flas the ApiParam annotation and then checking for it when creating the documentation.

earaya · 2013-04-19T17:48:30Z

@fehguy any interest on this? just wondering...

fehguy · 2013-04-19T18:04:48Z

Yes, getting there, and making sure it works across the models, etc.

znbailey · 2013-04-28T21:12:31Z

Would love this!

fehguy · 2013-05-24T04:50:22Z

The access() attribute is intended for this purpose. Custom filtering based on access is going in right now.

fehguy · 2013-05-28T04:19:02Z

see here, this is supported in the 1.3-develop branch, which will be pushed to master shortly:

https://github.com/wordnik/swagger-core/blob/develop-1.3/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiParam.java#L39

and the corresponding filter logic:

https://github.com/wordnik/swagger-core/blob/develop-1.3/modules/swagger-core/src/test/scala/filter/SpecFilterTest.scala#L44

earaya · 2013-05-30T04:28:39Z

Great! When do you expect 1.3 will be in Maven Central?

fehguy · 2013-05-30T06:14:17Z

there will be a snapshot this week

fehguy · 2013-05-31T16:38:44Z

added support in 1.3.0-SNAPSHOT. You create a filter and ignore whatever you like from params:

https://github.com/wordnik/swagger-core/blob/develop-1.3/modules/swagger-core/src/test/scala/filter/SpecFilterTest.scala#L44

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

earaya · 2013-06-01T15:09:40Z

Awesome! I really appreciate this. Can you post the maven coordinates? I wasn't able to find it in maven central.

Thanks again,
Esteban

fehguy · 2013-06-01T16:06:08Z

it's a snapshot, so you can find it in sonatype snapshots:

https://oss.sonatype.org/content/repositories/snapshots/com/wordnik/swagger-core_2.9.1/1.3.0-SNAPSHOT/

earaya · 2013-06-04T20:04:10Z

What about swagger-jaxrs? I don't see a 1.3.0 snapshot for that. In fact, it seems jaxrs support is back in version 2.8.1. Should I not be using swagger-jaxrs?

fehguy · 2013-06-04T20:21:15Z

see here:

https://oss.sonatype.org/content/repositories/snapshots/com/wordnik/swagger-jaxrs_2.9.1/1.3.0-SNAPSHOT/

and for jersey-specific:

https://oss.sonatype.org/content/repositories/snapshots/com/wordnik/swagger-jersey-jaxrs_2.9.1/1.3.0-SNAPSHOT/

earaya · 2013-06-05T21:13:23Z

Man, I'm so sorry to keep bugging you. What happened to JaxrsApiReader.setFormatString()? I can't find anything on why it was removed.

fehguy · 2013-06-05T21:16:00Z

Hey sorry for not replying. It was removed because of #123 which is something that everyone in the known universe has asked us. So there's no need to set the format string, because it is no longer there in 1.3.0-SNAPSHOT (and beyond)

earaya · 2013-06-06T03:57:38Z

Haha. Great! One less line of code for me. :)

earaya · 2013-06-06T17:09:46Z

Do you have an upgrade guide to 1.3.0? Once I switched, there's no data being returned from the documentation endpoint. It finds it, and it just returns {}.

fehguy · 2013-06-06T17:20:49Z

Guide isn't done yet but I can tell you that issue is because you don't have the swagger JSON providers in your scope. You can add those with the web.xml by scanning the com.wordnik.swagger.jaxrs.listing package:

https://github.com/wordnik/swagger-core/blob/develop-1.3/samples/java-jaxrs/src/main/webapp/WEB-INF/web.xml#L7

    <init-param>
      <param-name>com.sun.jersey.config.property.packages</param-name>
      <param-value>com.wordnik.swagger.jaxrs.listing</param-value>
    </init-param>

By programmatically adding them, as in the case of Dropwizard:

https://github.com/wordnik/swagger-core/blob/develop-1.3/samples/java-dropwizard/src/main/java/com/wordnik/swagger/sample/SwaggerSampleService.java#L28

  @Override
  public void run(SwaggerSampleConfiguration configuration, Environment environment) {
    environment.addResource(new ApiListingResourceJSON());
    environment.addResource(new PetResource());

    environment.addProvider(new ApiDeclarationProvider());
    environment.addProvider(new ResourceListingProvider());
    ScannerFactory.setScanner(new DefaultJaxrsScanner());
    ClassReaders.setReader(new DefaultJaxrsApiReader());
  }

Or through configuration, as with Apache-CXF:

https://github.com/wordnik/swagger-core/blob/develop-1.3/samples/java-jaxrs-cxf/src/main/resources/applicationContext.xml#L16

  <bean id="resourceWriter" class="com.wordnik.swagger.jaxrs.listing.ResourceListingProvider" />
  <bean id="apiWriter" class="com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider" />

  <bean class="org.apache.cxf.jaxrs.JAXRSServerFactoryBean" init-method="create">
    <property name="address" value="/" />
    <property name="serviceBeans">
      <list>
        <!-- the listing resource -->
        <ref bean="swaggerResourceJSON" />
      </list>
    </property>
    <property name="providers">
      <list>
        <!-- required for writing swagger classes -->
        <ref bean="resourceWriter" />
        <ref bean="apiWriter" />
      </list>
    </property>
  </bean>

tmazukna · 2013-09-27T13:14:03Z

I have created a custom filter which implements SwaggerSpecFilter to filter out apiParams injected by framework.

public class DwSwaggerInternalFilter implements SwaggerSpecFilter {

@Override
public boolean isOperationAllowed(Operation operation, ApiDescription apiDescription, Map<String, List<String>> stringListMap, Map<String, String> stringStringMap, Map<String, List<String>> stringListMap2) {
    return true;
}

@Override
public boolean isParamAllowed(Parameter parameter, Operation operation, ApiDescription apiDescription, Map<String, List<String>> stringListMap, Map<String, String> stringStringMap, Map<String, List<String>> stringListMap2) {
    if( parameter.paramAccess().isDefined() && parameter.paramAccess().get().equals("apiExclude") )
        return false;
    return true;
}

}

My code runs inside Dropwizard.
Here is my bundle run:

@Override
public void run(T dwConfiguration, Environment environment) {

    // Set the swagger config options
    SwaggerConfig config = ConfigFactory.config();
    DwSwaggerConfig configuration = findSwaggerConf(dwConfiguration);
    if( configuration != null ) {
        config.setApiVersion( configuration.getApiVersion() );
        config.setBasePath( configuration.getBasePath() );
    }

    // CORS Support for api-docs
    environment.addFilter(CrossOriginFilter.class, "/*");

    // Swagger Resource
    environment.addResource(new ApiListingResourceJSON());

    // Swagger providers
    environment.addProvider(new ApiDeclarationProvider());
    environment.addProvider(new ResourceListingProvider());

    // Swagger Scanner, which finds all the resources for @Api Annotations
    ScannerFactory.setScanner(new DefaultJaxrsScanner());

    // Add the reader, which scans the resources and extracts the resource information
    ClassReaders.setReader(new DefaultJaxrsApiReader());

}

How do I add my filter into swagger infrastructure?

Thanks!

peterstrapp · 2013-10-28T15:25:16Z

tmazukna, were you able to figure out how to register a SwaggerSpecFilter within a DropWizard project?

tmazukna · 2013-10-28T15:31:30Z

Yes,

this is how to do this:

FilterFactory.filter_$eq( new DwSwaggerInternalFilter() );

filter is defined as a property in Scala, but in JAva you see this strange method signature for a setter ;)
This is in 2.10 version of swagger.
I opened a change request with swagger team to fix the api, so later versions may have a proper setter and getter.

Tomas

peterstrapp · 2013-10-28T17:16:45Z

Great! Thanks Tomas, that works perfectly.

Peter

shalucsekaran · 2014-03-06T10:09:54Z

Thanks Tomas. Your solution worked perfectly... Appreciate you shared the solution....

Shalini

fehguy · 2014-03-15T00:09:31Z

This is pushed in 1.3.3-SNAPSHOT for both @ApiOperation and @ApiModelProperty. There is now a hidden property on both annotations that allow you to filter away fields and methods.

apemberton · 2014-04-21T03:51:21Z

@fehguy just checking - but should the hidden=true flag also be added to @ApiParam? Or should we continue to write custom filters for those?

fehguy · 2014-04-21T04:19:45Z

Hi, I believe you can now use hidden=true instead of the custom filter. Both should work

apemberton · 2014-04-21T11:20:05Z

Tried this to no effect. Is there a certain version of swagger core and swagger ui you need to be on for this?

Sent from my iPhone

On Apr 21, 2014, at 12:19 AM, Tony Tam notifications@github.com wrote:

Hi, I believe you can now use hidden=true instead of the custom filter. Both should work

—
Reply to this email directly or view it on GitHub.

webron · 2014-04-27T12:39:54Z

For hidden=true, you need swagger-core 1.3.4. swagger-ui version is irrelevant.

pofallon · 2014-10-18T18:24:00Z

@fehguy Is hidden=true available in ApiParam now? I'm on 1.3.10 and don't see it. Having that option would be much preferred to standing up a servlet filter just for this one feature (especially in JAX-RS deployments that aren't already using servlets -- like those on Grizzly).

Or, if that's not an option, is there some guidance on how to deploy a SwaggerSpecFilter as a JAX-RS 2.0 ContainerResponseFilter? (That would probably be good to know anyway for other uses of "access"). Thanks!

fehguy · 2014-10-18T20:38:30Z

it looks like there isn't a hidden field in a parameter, only in ApiOperation and ApiModelProperties.

If you want to remove a parameter, you can simply create a filter like such:

https://github.com/wordnik/swagger-core/blob/master/samples/java-jaxrs/src/main/java/com/wordnik/swagger/sample/util/ApiAuthorizationFilterImpl.java#L60

Note implementing your own logic for the isParamAllowed will make the field visible or not.

pofallon · 2014-10-20T01:49:34Z

@fehguy Thanks for the reply! I did see that mentioned in the thread, but it wasn't entirely obvious how to do this for a JAX-RS 2.0 app that's not using servlets. I ended up implementing a ContainerResponseFilter (see gist) which appears to work. However, is it expected that I would need to interact directly with SpecFilter.filter() this way? Thanks again for your feedback!

fehguy · 2014-10-20T03:52:36Z

You shouldn't need to handle it on your own--the swagger framework will apply the filter on it's own. See here how it's configured:

https://github.com/wordnik/swagger-core/blob/master/samples/java-jaxrs/src/main/webapp/WEB-INF/web.xml#L44-L47

    <init-param>
      <param-name>swagger.filter</param-name>
      <param-value>com.wordnik.swagger.sample.util.ApiAuthorizationFilterImpl</param-value>
    </init-param>

pofallon · 2014-10-24T23:49:30Z

DefaultJaxrsConfig seems to expect a servlet (which I don't have). Is there a way to set the swagger.filter property in an environment without any servlets or web.xml?

I'm currently initializing Swagger with the following code in my Main.java class:

        SwaggerConfig swaggerConfig = new SwaggerConfig();
        ConfigFactory.setConfig(swaggerConfig);
        swaggerConfig.setSwaggerVersion("2.0");
        swaggerConfig.setBasePath(BASE_URI);
        swaggerConfig.setApiVersion("1.0.0");
        ScannerFactory.setScanner(new DefaultJaxrsScanner());
        ClassReaders.setReader(new DefaultJaxrsApiReader());

Thanks!

webron · 2014-10-25T07:30:21Z

@pofallon - Yes. You can use the BeanConfig class to set the filter.

Ignore ApiParam.

7336556

There are several scenarios, which may necessitate a parameter to be excluded from the documentation. This works by adding an ignore flas the ApiParam annotation and then checking for it when creating the documentation.

ghost assigned fehguy May 24, 2013

fehguy closed this May 31, 2013

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Ignore ApiParam. #167

Ignore ApiParam. #167

earaya commented Apr 3, 2013

earaya commented Apr 19, 2013

fehguy commented Apr 19, 2013

znbailey commented Apr 28, 2013

fehguy commented May 24, 2013

fehguy commented May 28, 2013

earaya commented May 30, 2013

fehguy commented May 30, 2013

fehguy commented May 31, 2013

earaya commented Jun 1, 2013

fehguy commented Jun 1, 2013

earaya commented Jun 4, 2013

fehguy commented Jun 4, 2013

earaya commented Jun 5, 2013

fehguy commented Jun 5, 2013

earaya commented Jun 6, 2013

earaya commented Jun 6, 2013

fehguy commented Jun 6, 2013

tmazukna commented Sep 27, 2013

peterstrapp commented Oct 28, 2013

tmazukna commented Oct 28, 2013

peterstrapp commented Oct 28, 2013

shalucsekaran commented Mar 6, 2014

fehguy commented Mar 15, 2014

apemberton commented Apr 21, 2014

fehguy commented Apr 21, 2014

apemberton commented Apr 21, 2014

webron commented Apr 27, 2014

pofallon commented Oct 18, 2014

fehguy commented Oct 18, 2014

pofallon commented Oct 20, 2014

fehguy commented Oct 20, 2014

pofallon commented Oct 24, 2014

webron commented Oct 25, 2014

Ignore ApiParam. #167

Ignore ApiParam. #167

Conversation

earaya commented Apr 3, 2013

earaya commented Apr 19, 2013

fehguy commented Apr 19, 2013

znbailey commented Apr 28, 2013

fehguy commented May 24, 2013

fehguy commented May 28, 2013

earaya commented May 30, 2013

fehguy commented May 30, 2013

fehguy commented May 31, 2013

earaya commented Jun 1, 2013

fehguy commented Jun 1, 2013

earaya commented Jun 4, 2013

fehguy commented Jun 4, 2013

earaya commented Jun 5, 2013

fehguy commented Jun 5, 2013

earaya commented Jun 6, 2013

earaya commented Jun 6, 2013

fehguy commented Jun 6, 2013

tmazukna commented Sep 27, 2013

peterstrapp commented Oct 28, 2013

tmazukna commented Oct 28, 2013

peterstrapp commented Oct 28, 2013

shalucsekaran commented Mar 6, 2014

fehguy commented Mar 15, 2014

apemberton commented Apr 21, 2014

fehguy commented Apr 21, 2014

apemberton commented Apr 21, 2014

webron commented Apr 27, 2014

pofallon commented Oct 18, 2014

fehguy commented Oct 18, 2014

pofallon commented Oct 20, 2014

fehguy commented Oct 20, 2014

pofallon commented Oct 24, 2014

webron commented Oct 25, 2014