Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Spring MVC integration for Swagger

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
.cache
.gitignore
pom.xml
readme.md

readme.md

Swagger / Spring MVC Integration

This project provides integration between Swagger and Spring MVC.

Spring beans annotated with @Controller are detected and parsed for documentation.

Getting started

The project is available from maven:

<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>0.3.0</version>
</dependency>

Supported annotations

Currently, a subset of Swagger annotations are supported. Support will improve over the coming releases.

All @Controller classes are parsed, and methods annotated with @RequestMapping are generated.

Additionally, @Api at the class level, and @ApiOperation at the method level are both supported.

Getting started

To wire up support, add the following into your `*-servlet.xml context:

<context:component-scan base-package="com.mangofactory.swagger.spring.controller" use-default-filters="false">
    <context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/>
</context:component-scan>
<bean id="swaggerConfiguration" class="com.mangofactory.swagger.SwaggerConfiguration">
    <property name="basePath" value="http://www.mydomain.com/swagger-springmvc-example/"/>
    <property name="apiVersion" value="1.0"/>
    <property name="excludedResources">
        <list>
            <value>/controller-uri-to-exclude</value>
        </list>
    </property>
</bean>

The basePath property is external-facing url the maps to your SpringMVC dispatcher servlet.

This creates a controller at /api-docs from this uri, which serves swagger's raw documentation in JSON format. (eg ., In the above example, http://www.mydomain.com/swagger-springmvc-example/api-docs)

Deviations from default Swagger API

Some deviations from the default Swagger API exist. Wherever possible, these are inteded to be implemented as-well-as the default Swagger implementation, rather than as a replacement.

The overarching goal is to support generation of the Swagger JSON, with minimal intrusion to the code itself.

Errors

Declaration of errors supports the standard Swagger @ApiErrors and @ApiError annotations. In addition, there are com.mangofactory.swagger implementations of these that reduce the amount of per-method code (notably, at the cost of some flexibility)

@ApiError is now supported at the exception class level, as shown here:

@ApiError(code=302,reason="Malformed request")
public class BadRequestException {}

This allows errors to be declared as follows:

@ApiErrors({NotFoundException.class,BadRequestException.class})
public void someApiMethod() {};

or, simply using a throws declaration:

public void someApiMethod() throws NotFoundException, BadRequestException {};

Example project

An example of Swaggers PetStore in Spring MVC is available here

TODO:

  • Handle the case where RequestMapping may represent more than one value
  • Handle the case where RequestMapping might have wildcards
Something went wrong with that request. Please try again.