How to use swagger with OAuth API?

Question

Is it possible to use swagger as a documentation/testing tool for APIs that use OAuth2? I don't see anything on the swagger site (or anywhere else for that matter). Every usage I've seen uses either an API key, HTTP basic, or cookies.

Answer 1

I have been working along the same lines. Swagger will accept any header or URL defined api key or token. Adding a validation helper to the api and app is a standard approach.

Oauth does require a HTML review and or login to start the handshake aouth process. This means that a swagger api will need to support a web interface for a standard login and scope acceptance. Rolling oauth into swagger results in a few logic loops, which long term are not easy to support.

A different approach we are exploring is the option to let the api handle and store access tokens for a number of different oauth providers; GitHub, twitter and Facebook. This might result in login loops as well.

Answer 2

late to the party here but oAuth support is now in 1.3.0-RC1 of swagger-core. The javascript library which can support oAuth was released yesterday in swagger-js. Finally, the swagger-ui is in develop phase, and will soon have a oAuth implicit and server flow.

Answer 3

the blog´s post http://developers-blog.helloreverb.com/enabling-oauth-with-swagger/ cited by @fehguy shows an example of java code to include the authorization data in json generated by swagger, however my question was where it should be included with app with Spring, JAXRS and CXF. I didn´t find it in CXF + JAXRS Sample :https://github.com/swagger-api/swagger-core/tree/master/samples/java-jaxrs-cxf

However, looking for a bit more and gotcha !

https://github.com/swagger-api/swagger-core/blob/master/samples/java-jersey-spring/src/main/resources/beans-asset-ws.xml

Is necessary include a Bean with a class called Bootstrap (extends HttpServlet) and a static block !

Opinion: Maybe it would be more “spring-friendly” loaded from annotations by SwaggerConfig Scanner in Rest class instead a static block in a servlet.

Answer 4

@Configuration
public class SwaggerConfiguration {

    @Bean
    @DependsOn("jaxRsServer") //org.apache.cxf.endpoint.Server bean
    public ServletContextInitializer initializer() {
        return new ServletContextInitializer() {
            @Override
            public void onStartup(ServletContext servletContext) throws ServletException {
                BeanConfig scanner = (BeanConfig) ScannerFactory.getScanner();
                Swagger swagger = scanner.getSwagger();
                servletContext.setAttribute("swagger", swagger);
            }
        };
    }

    @Bean
    public Feature swaggerFeature() {
        XSwagger2Feature feature = new XSwagger2Feature();

        return feature;
    }

    @Bean
    public FilterRegistrationBean swaggerApiFilter() {
        ApiOriginFilter filter = new ApiOriginFilter();

        FilterRegistrationBean registrationBean = new FilterRegistrationBean();
        registrationBean.setFilter(filter);
        registrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE);

        return registrationBean;
    }

    public static class XSwagger2Feature extends Swagger2Feature {

        @Override
        protected void addSwaggerResource(Server server) {
            super.addSwaggerResource(server);

            BeanConfig scanner = (BeanConfig) ScannerFactory.getScanner();
            Swagger swagger = scanner.getSwagger();
            swagger.securityDefinition("api_key", new ApiKeyAuthDefinition("api_key", In.HEADER));
            swagger.securityDefinition("petstore_auth", 
              new OAuth2Definition()
                .implicit("http://petstore.swagger.io/api/oauth/dialog")
                .scope("read:pets", "read your pets")
                .scope("write:pets", "modify pets in your account"));
        }

    }

}

Answer 5

IOdocs from mashery seems to support OAuth, but it's quite different from swagger (redis, node, etc.). It's available on github.