Can a Java Spring application take advantage of swagger

Question

I've been looking into swagger as a possible way to automatically generate documentation for my team's api http://swagger.io/getting-started/. It seems very promising, but I find their documentation lacking.

That being said I have a few very basic questions.

1. Is it possible to use swagger with just a Spring application? Our application is neither a jersey or JAX-RS application. Does anyone know if a plain Spring application can be used with swagger? If so can a link or set of instructions be provided?

I'd found this link http://blog.zenika.com/index.php?post/2013/07/11/Documenting-a-REST-API-with-Swagger-and-Spring-MVC however they skim over the bits about setting the properties file.

2. swagger cites many different tools on their site swagger core, codegen, ui, and swagger editor. Is only swagger-core needed to generate their basic API documentation or is a combination of swagger tools required?

Answer 1

There is a page dedicate to support swagger frameworks.

What you are looking for is SpringFox.

Automated JSON API documentation for API's built with Spring

Basically you apply the configuration using a Docket object like this pointing to your API context. You'll have to take your time since there is a little bit of configuration for making it to work, not mentioning scaling it to your application needs.

 @Bean
    public Docket documentation() {
        return new Docket()
          .select()
            .apis(RequestHandlerSelectors.any())
            .paths(regex("/api/.*"))
            .build()
          .pathMapping("/")
          .apiInfo(metadata());
    }

As you might already know, you can add annotations such as possible HTTP response codes, etc, among many other capabilities. Very promising indeed.

@ApiOperation(value = "doStuff", nickname = "doStuff", response = DoStuffResult.class)
@Responses({
    @ApiResponse(code =  404, message ="Not found", response = GenericError.class),
    @ApiResponse(code =  400, message ="Invalid input", response = GenericError.class)
})
@RequestMapping(method = RequestMethod.GET, produces = "application/json")
public ResponseEntity<?> doStuff(@RequestBody DoStuffCommand command) {
    // Stuff
}

Here is the best example I could find online, very short and objective.

Answer 2

For me following worked:

Added the following dependencies to the pom:

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

Then added @EnableSwagger2 to the spring configuration file and registered resource handler needed for the swagger UI like:

@Configuration
public class YourConfigFileHere extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/resources/**").addResourceLocations(
            "/resources/");

        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
            "classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**").addResourceLocations(
            "classpath:/META-INF/resources/webjars/");
    }

    // rest of the configuration
}

This would get the basic swagger UI up and running. If you want to customize, you can do so by adding a swagger configuration file annotated with @EnableSwagger2 and import it into spring configuration file with @Import.

For local environment, you can access swagger-ui at:

http://localhost:8080/{context-root}/swagger-ui.html

Answer 3

As stated above, springfox is a first-class swagger library for spring-mvc. You can also use spring configuration as demonstrated in the swagger-samples repository.

You can see an example of this working by visiting http://editor.swagger.io and creating a swagger definition. From there, you can download a spring-mvc server with swagger support.