Document Spring OAuth 2.0 APIs using Swagger

Question

I am working on setting up an OAuth 2.0 authorization server using Spring security. I would like to document the OAuth 2.0 APIs using Swagger. How should I go about doing it?

Answer 1

I am currently working on it and I am using the Springfox library to document it.

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency>

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency>

My Swagger Config looks like this:

    @Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public Docket documentation() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
            .useDefaultResponseMessages(false)
            .pathMapping("/")
            .apiInfo(apiInfo());
    }



    /**
     * API INFO
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx")
                .description("xxx")
                .version("xxx")                 
                .contact("xxx")
                .build();
    }
}

One Part of one of my Endpoints (Note: There was no proper way to annotate a Map. 2.4.0 added Support but i haven't tried it yet.)

@Api(value = "xxx")
@FrameworkEndpoint
@SessionAttributes("authorizationRequest")
public class OAuthAuthorizationEndpoint {

    private AuthorizationEndpoint authorizationEndpoint;

    /**
     * @param endpoint
     *      base AuthorizationCheckpoint
     */
    public OAuthAuthorizationEndpoint(AuthorizationEndpoint endpoint){
        this.authorizationEndpoint = endpoint;
    }
@ApiOperation(value = "xxx", httpMethod = "GET", notes = "xxx")
    @ApiResponses(value = {
            @ApiResponse(code = 400, message = "Invalid input:...", response = Auth400Response.class),
            @ApiResponse(code = 200, message = "Ok", response = Auth200Response.class)
            })  
    @RequestMapping(value = "/oauth/authorize", produces = "application/json")
    @ResponseBody
    public ModelAndView authorize(@ApiIgnore Map<String, Object> model,
            @ApiParam(value = "xxx", required = true, defaultValue = "xxx") @RequestParam String response_type, 
            @ApiParam(value = "xxx", required = true) @RequestParam String client_id, 
            @ApiParam(value = "xxx", required = true) @RequestParam String redirect_uri, 
            @ApiParam(value = "xxx", required = false, defaultValue = "/") @RequestParam String realm,
            @ApiParam(value = "xxx", required = false) @RequestParam String state,
            @ApiIgnore SessionStatus sessionStatus, @ApiIgnore Principal principal){
        Map<String, String> parameters = new HashMap<String, String>();
        parameters.put("response_type", response_type);
        parameters.put("client_id", client_id);
        parameters.put("realm", realm);
        parameters.put("redirect_uri", redirect_uri);
        parameters.put("state", state);
        return this.authorizationEndpoint.authorize(model, parameters, sessionStatus, principal);

This might help you.