Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Spring MVC integration for Swagger

This branch is 1059 commits behind springfox:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
.cache
.gitignore
pom.xml
readme.md
releasing.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.4</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
  • Handle enums in models do not currently get rendered correctly in the model schema. Fix this to accomodate DocumentSchema shortcomings
Something went wrong with that request. Please try again.