Allow exclusion of endpoints

[haakobja]

Filtering/exclusion of endpoints should be allowed.

It would be nice to be able to filter which endpoints should be exported to Swagger.yaml using the @ApiModelProperty(access="...") annotation.

Following is an example of my proposal:

@Path(TestClass.PATH)
public class TestClass {
    static final String PATH = "/path/goes/here";
    @Get
    @ApiOperation( value= "I'm hidden from the public")
    @ApiModelProperty(name = "hiddenMethod", access="internal")
    public Response hiddenMethod() {
        ...
    }
    @Post
    @ApiOperation( value= "Go ahead. Use me")
    public Response freeForAll(Thingy thingy) {
        ...
    }
}

POM:

<plugins>
    <plugin>
        <artifactId>swagger-maven-plugin</artifactId>
        ...
        <configuration>
            <apiSources>
                <apiSource>
                    <locations>
                        example.endpoints
                    </locations>
                    <apiModelPropertyAccessExclusions>
                        <apiModelPropertyAccessExclusion>
                            internal
                        </apiModelPropertyAccessExclusion>
                    </apiModelPropertyAccessExclusions>
                    <swaggerDirectory>public</swaggerDirectory>
                </apiSource>
                <apiSource>
                    <locations>
                        example.endpoints
                    </locations>
                    <swaggerDirectory>internal</swaggerDirectory>
                </apiSource>
            </apiSources>
        </configuration>
    </plugin>
</plugins>

This would produce two yaml-files, one including the /path/goes/here-GET and one excluding it

[carlosjgp]

Looks like you already can do it!

https://github.com/kongchen/swagger-maven-plugin#excluding-certain-apimodelproperty-items

[haakobja]

Yes, it does work for the objects returned from an endpoint. My case is that I want to exclude certain endpoints, not only their request/response objects.

[HugoDife]

I know some time had passed, but using @Api(hidden = true) should hide it. I used it in the whole class not in the function linked to an endpoint. Hope it helps.

[haakobja]

Yes, I know about the @Api(hidden = true), but as you say, this works on classes, not methods.

I have tried to think about this, and it would be nice to use the security definitions to do this filtering. The pom-configuration could have a "include auth"-tag, where it would be possible to define the security definitions which should be output in the file.

Like this

<configuration>
  <includeAuth>
    <auth type="myBasic" />
    <auth type="myOauth" scope="read" />
  </includeAuth>
</configuration>

If it is used on a class like this

public class Endpoints {
  @ApiOperation(
    authorizations = {
      @Authorization("myApiKey")
    }
  )
  public Response securedWithAPIKey() {}

  @ApiOperation(
    authorizations = {
      @Authorization("myOAuth", {@AuthorizationScope("read")})
    }
  )
  public Response securedWithOauthRead() {}

  @ApiOperation(
    authorizations = {
      @Authorization("myOAuth", {@AuthorizationScope("write")})
    }
  )
  public Response securedWithOauthWrite(Input) {}

  @ApiOperation(
    authorizations = {
      @Authorization("myBasic")
    }
  )
  public Response securedWithBasic() {}
}

In this example, the securedWithBasic and securedWithOauthRead should be output in the swagger.yaml

[zarub2k]

I am also expecting the same behavior. In a class I would like to exclude few REST endpoints from the swagger generation. Because those endpoints are only for internal usage. Not for public usage.

Is there any progress or how to achieve this?

[zarub2k]

@APIOperation(hidden=true) with this annotation we can ignore the rest endpoints while generating Swagger

[amwebexpert]

This works thanks @zarub2k :-) @ApiOperation(value = "", hidden = true)

[praveenjayapal-github]

We are using swagger-maven-plugin to generate swagger documentation. we have the proper annotation for each class and respective method (all API). We are in the need of generating the swagger documentation, and it's generating with all my API's in a single document.

Requirement: Is that possible to generate two set of swagger documents based on the some categorization?Here i am trying to categorize with "public" and "private" As per https://github.com/kongchen/swagger-maven-plugin/blob/master/README.md, I have used apiModelPropertyAccessExclusions but it's not working.

@ApiModelProperty(name="addReport", access="public", hidden=true)

pom.xml::

<apiModelPropertyAccessExclusions>
    <apiModelPropertyAccessExclusion>public</apiModelPropertyAccessExclusion>
</apiModelPropertyAccessExclusions>

It's not working as expected. Please help me out.

[amaravathi]

Looking for the same solution , the search is still on, I am not able to achieve this either

[jahlbornG]

we would also love for a good way to generate public and private docs separately. we use the hidden flag on a lot of stuff. it'd be nice to simple have an option like "ignore hidden" which would include everyting.