Ability to add custom ApiDescriptions not described via request mappings

[romanwozniak]

I'm using springfox-swagger2 v2.4.0 in a project that uses Spring OAuth2 authentication flow.

My swagger config looks like this:

@Configuration
@EnableSwagger2
@ComponentScan(
        basePackages = "com.comergence.appraiser.api.controller"
)
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("/applicants/.*"))
                .build()

}

Now I want to document OAuth endpoints. I don't like what is generated by default for this endpoints and I can't modify this, because controllers that serve oauth endpoints are part of spring-security-oauth2 library.

So, I thought that I can add custom operation into swagger by extending ApiListingBuilderPlugin.
I created this @Bean

@Component
@Order(value= SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER)
public class OAuthApiListing implements ApiListingBuilderPlugin {

    @Override
    public void apply(ApiListingContext apiListingContext) {
        apiListingContext
                .apiListingBuilder()
                .apis(
                    newArrayList(
                            new ApiDescription(
                                    "/oauth/token",
                                    "OAuth Endpoints",
                                    newArrayList(
                                            new Operation(
                                                    HttpMethod.POST,
                                                    "Retrieve Access Token",
                                                    "",
                                                    null,
                                                    "oauth-token",
                                                    0,
                                                    Collections.emptySet(),
                                                    newHashSet(MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE),
                                                    newHashSet(MediaType.APPLICATION_FORM_URLENCODED_VALUE),
                                                    Collections.emptySet(),
                                                    newArrayList(),
                                                    newArrayList(
                                                            new Parameter(
                                                                    "grant_type",
                                                                    "Grant type",
                                                                    "client_credentials",
                                                                    true,
                                                                    false,
                                                                    new ModelRef("java.lang.String"),
                                                                    null,
                                                                    new AllowableListValues(newArrayList("client_credentials", "authorize_code"), "String"),
                                                                    "form",
                                                                    ""
                                                            )
                                                    ),
                                                    newHashSet(
                                                            new ResponseMessage(
                                                                    HttpStatus.OK.value(),
                                                                    HttpStatus.OK.getReasonPhrase(),
                                                                    new ModelRef("org.springframework.security.oauth2.common.DefaultOAuth2AccessToken"),
                                                                    Collections.emptyMap()
                                                            )
                                                    ),
                                                    null,
                                                    false,
                                                    newArrayList()
                                            )
                                    ),
                                    false
                            )
                    )
                );
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }
}

Overall it's doing what I need, but the problem is that it overrides all api listing generated by springfox.documentation.spring.web.scanners.ApiListingScanner, so resulting api-docs json contains only /oauth/token api operation, that was described manually in OAuthApiListing.

I'm not sure if this is correct way to add some documented operation into swagger. So, please, point me out if there is other way.
Thanks.

[dilipkrish]

This would be a nice feature thanks for reporting. Would you like to take a stab at a PR?

[huiwang]

I'm in the same context. Has the PR been prepared?

[batalkin]

Was forced to does this

@Override
    @SuppressWarnings("unchecked")
    public void apply(ApiListingContext apiListingContext) {
        ApiListingBuilder builder = apiListingContext.apiListingBuilder();

        Field field = ReflectionUtils.findField(builder.getClass(), "apis");
        ReflectionUtils.makeAccessible(field);
        Object value = Optional.ofNullable(ReflectionUtils.getField(field, builder)).orElse(Collections.emptyList());
        List<ApiDescription> apis = (List<ApiDescription>) value;

        List<ApiDescription> newApis = new ArrayList<>(apis);
        newApis.addAll(additionalOperations);
        builder.apis(newApis);
    }

Hope this feature will be in the next release

[batalkin]

Does anybody work on this? Or I can take a look at this feature?

[dilipkrish]

@batalkin that would be awesome. Let me know what you're plans are just to make sure its in line with the direction of the library and Id be happy to answer any questions you might have