How to hide some APIs from swagger UI?

[Wendy Huang]

Hi,

We have a requirement to hide some API display on swagger UI. Is there a way to do that?

Thanks,
Wendy

[Ron]

Which Swagger library do you use to generate the documentation?

Should the API be hidden to everyone or based on some condition?

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Wendy Huang]

Hi Ron,

We use swagger-jaxrs_2.10 1.3.2 version. API hide for everyone is good enough.

Thanks,
Wendy

On Wednesday, March 26, 2014 9:17:32 PM UTC-7, Ron R wrote:

Which Swagger library do you use to generate the documentation?

Should the API be hidden to everyone or based on some condition?

On Mar 27, 2014 2:39 AM, "Wendy Huang" <qinye...@gmail.com> wrote:

Hi,

We have a requirement to hide some API display on swagger UI. Is there a way to do that?

Thanks,
Wendy

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[tony tam]

1.3.3-SNAPSHOT has a hidden attribute:

https://github.com/wordnik/swagger-core/blob/develop/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiOperation.java#L74

[Wendy Huang]

Hi Tony,

Thanks! Is it possible to make this attribute as configuration parameter, so we can enable or disable when start the application?

Thanks,
Wendy

[tony tam]

Yes, this is precisely the purpose of the SwaggerFilter.  Take a look at this unit test as an example.

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

Which is testing the following filter:

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

  }

}

Tony

[Wendy Huang]

Hi Tony,

This sounds great! Do you have an example or document to show how  SwaggerFilter works in Java?

Thanks,
Wendy

[Ron]

Hi Wendy,

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

Don't forget to define the filter in your web.xml (check the sample).

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Wendy Huang]

Hi Ron,

I downloaded the sample. When I access from browser with: http://localhost:8002/api/api-docs

{"apiVersion":"1.0.0","swaggerVersion":"1.2","apis":[{"path":"/pet","description":"Operations about pets"},{"path":"/user","description":"Operations about user"}],"authorizations":{"oauth2":{"type":"oauth2","scopes":[{"scope":"email","description":"Access to your email address"},{"scope":"pets","description":"Access to your pets"}],"grantTypes":{"implicit":{"loginEndpoint":{"url":"http://localhost:8002/oauth/dialog"},"tokenName":"access_code"}}}},"info":{"title":"Swagger Sample App","description":"This is a sample server Petstore server.  You can find out more about Swagger at <a href=\"http://swagger.wordnik.com\">http://swagger.wordnik.com</a> or on irc.freenode.net, #swagger.  For this sample, you can use the api key \"special-key\" to test the authorization filters","termsOfServiceUrl":"http://helloreverb.com/terms/","contact":"api...@wordnik.com","license":"Apache 2.0","licenseUrl":"http://www.apache.org/licenses/LICENSE-2.0.html"}}

Also I have questions:

1) We use dropwizard so there is no web.xml. How to initialize the filter in dropwizard please?
2) Where to specify something like "api-key" and value "special-key"? I didn't find in the example online. Actually the downloaded files are in scala not java and I didn't see these setting also.

Thanks,
Wendy

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Ron]

If you're using dropwizard, check out the dropwizard sample - https://github.com/wordnik/swagger-core/tree/master/samples/java-dropwizard.

Basically, if it doesn't use web.xml, it probably relies on the Servlet 3.0+ spec, which allows you to annotate classes for their functionality rather than describing them in the web.xml.

Look for the documentation of @WebFilter - http://docs.oracle.com/javaee/6/api/javax/servlet/annotation/WebFilter.html

As for the api-key - that depends if you're looking to set that on accessing the API documentation or the API itself.

For the API documentation - check this - https://github.com/wordnik/swagger-core/blob/c927515d0bee916ac729c48ba516bec2c436de2a/samples/java-jaxrs/src/main/java/com/wordnik/swagger/sample/util/ApiAuthorizationFilterImpl.java

For the API itself, the control over which API you use is entirely up to the framework that you use. I don't have  a specific example of how to add the description for it in Java, but if you need that let me know and I'll walk you through it.

Keep it mind that under no case would you keep the value in the documentation. If you do, it's pretty much pointless to have it.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Wendy Huang]

Hi Ron,

Thanks for @WebFilter.

I'm looking for api documentation only. However I think I do not understand well about api-key. For example, if there are two keys: default-key (all APIs show up in document) and special-key (only some APIs show up in documentation GUI), besides the filter, how to link api-key (special-key) to API I do not want to show?

Thanks,
Wendy

[Ron]

Wendy,

I fear there may not be a simple solution for that at the moment.

@ApiParam has an access field which you can use to filter out those parameters, but this field does not exist in @ApiOperation.

You can write a workaround to this by using an @ApiImpicitParam annotation - here are your steps:

1. Add an @ApiImplicitParam with access="special", you can also name it "special" or some other constant name.
   
2. In the isOperationAllowed method, check if that parameter exists inside the operation.
   
1. If it does, check that it also exists with the proper value in the parameters received
   
1. if the value is proper, allow this operation
2. if not, don't allow it
2. if it doesn't, allow the operation
3. In the isParamAllowed method, if the param is the one with the "special" access, never allow it (that way it'll never actually be documented).

Feel free to open an issue on Swagger-Core about adding an "access" field to @ApiOperation. Currently (version 1.3.4) we added a 'hidden' field, but that's either true/false and can't be used to dynamically decide whether it should be included or not.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Wendy Huang]

Hi Ron,

Thanks a lot of the info. I'll try it.

I have a question regarding @WebFilter. This is what I added for ApiAuthorizationFilterImpl:

@WebFilter(filterName = "ApiAuthorizationFilterImpl",
urlPatterns = {"/*"})
public class ApiAuthorizationFilterImpl implements SwaggerSpecFilter {
...
}

Is it correct? I run my app in debug mode and didn't see any functions in ApiAuthorizationFilterImpl get called.

Thank you,
Wendy

[Ron]

I believe it should be fine, though I've never written a filter myself that way.

I'm sure some google search can help you out if it doesn't hit anything.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Wendy Huang]

Hi Ron,

Is it because of ApiAuthorizationFilterImpl is from SpecFilter.scala, it's not recognized as a filter? I tried to add filter with dropwizard environment.addFilter function and is failed. If I cast ApiAuthorizationFilterImpl to filter class, I got run time error.

Any suggestion?

Thanks,
Wendy

[Ron]

Maybe this would help - http://stackoverflow.com/questions/19166603/custom-jetty-filters-in-dropwizard

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[tony tam]

Hi, you can enable a swagger filter (i.e. a class which implements com.wordnik.swagger.core.filter.SwaggerSpecFilter) like such:

FilterFactory.setFilter(new MyCustomFilter());

This would typically live in your Dropwizard Service class.

[Wendy Huang]

Hi Ron,

The link shows the same thing like I did. The only difference is there is no environment.servlets() in new dropwizard package, instead I use environment.addFilter, the problem is ApiAuthorizationFilterImpl which implement SwaggerSpecFilter is not considered a filter and code got error.

Also, even if I can add the filter, the filtering work is done in "doFilter" function, how can we make isOperationAllowed and isParamAllowed to be executed?

Thanks,
Wendy

[Wendy Huang]

Hi Tony,

I tried your code in dropwizard service class and failed also. There is no "setFilter" function in two FilterFactory classes which Eclipse pop up. What FilterFactory you mean?

Thank you,
Wendy

[tony tam]

com.wordnik.swagger.config.FilterFactory

For example:

@Override

public void run(SwaggerSampleConfiguration configuration, Environment environment) {

  environment.addResource(new ApiListingResourceJSON());

  environment.addResource(new PetResource());

  environment.addProvider(new ResourceListingProvider());

  environment.addProvider(new ApiDeclarationProvider());

  ScannerFactory.setScanner(new DefaultJaxrsScanner());

  ClassReaders.setReader(new DefaultJaxrsApiReader());

  FilterFactory.setFilter(new ApiAuthorizationFilterImpl());

  SwaggerConfig config = ConfigFactory.config();

  config.setApiVersion("1.0.1");

  config.setBasePath("http://localhost:8000");

[Wendy Huang]

Hi Tony,

I use the same class, the swagger-core package is not added into my module, I fixed it and now the functions in  ApiAuthorizationFilterImpl are executed.

However the parameter I set in @ApiImplicitParam is not catched. params is always empty and parameter in "isParameterAllowed" function doesn't show the parameter I set with @ApiImplicitParam.

Did I miss something?

Thanks,
Wendy
 

[tony tam]

So this is a different issue, you have the filter working, correct?

Did you follow one of the samples for the implicit parameters?

[Wendy Huang]

Hi Tony,

Now it works as expected! I need to use @ApiImplicitParams.

Thanks a lot,
Wendy

[Wendy Huang]

Hello,

The implicit parameter shows up in swagger GUI. Doesn't look good. How to hide it please?

Thanks,
Wendy

[tony tam]

They're supposed to show up--implicit parameters are unbound to a function variable.  If you don't want them to appear, you can remove the implicit annotation.

[Wendy Huang]

Hi Tony,

If I remove implicit, it seems become  @ApiParam and I have to define a variable in function input. Do you have an example to do this in a more elegant way?

Thanks,
Wendy

[Wendy Huang]

After I strictly follow Ron's instruction, the implicit parameter won't show up anymore. Thanks Ron.

Wendy

[Gautam Priya]

Ron,

I ran into the simpler use case of hiding a ApiOperation without any condition and on learning that hidden was added to swagger 1.3.4/1.35, I switched to swagger version 1.3.5. Then I annotated the public method that I intend to hide and set hidden to true. This had no effect :( After a couple iterations, I found out that support for this attribute has not yet been implemented yet. Please see issue that was opened 20 days back - https://github.com/martypitt/swagger-springmvc/issues/447

[Gautam Priya]

@webron - would appreciate if you would confirm that hidden attribute of ApiOpreation has been fully implemented in swagger-jaxrs_2.10. Thanks much

[tony tam]

Hi Gautam, I've verified it exists in 1.3.5 and later:

https://github.com/wordnik/swagger-core/blob/swagger-project_2.10.0-1.3.7/modules/swagger-jaxrs/src/main/scala/com/wordnik/swagger/jaxrs/JaxrsApiReader.scala#L235-L240

It also appears to NOT be implemented in the spring-mvc module.

[Gautam Priya]

Hi Tony,

I moved to swagger-jaxrs_2.10 1.3.5 and it worked like a charm. Much appreciated.

A related question - which version of swagger-jaxrs_2.10 introduced and implemented the hidden attribute on @ApiModelProperty. It seems like it is available in 1.3.5 as well.

Thanks

[sami...@gmail.com]

Hi,

I'm using Swagger 1.2 and Spring-MVC.

I was hoping someone could point me in the right direction.

I don't the jetty-filters would work in my case.

Thanks!

[Ron Ratovsky]

You'd need to visit swagger-springmvc's docs to see how to filter the operations (or migrate to springfox).

Ron,

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Abhishek Gupta]

Hi Tony,

Can you help me in configuring SwaggerSpecFilter in SPringBoot application? 

I tried using FilterFactory.setFilter (new MySwaggerFiler());

But it didn't help.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.