Swagger生成API文档

一、swagger介绍

使用springMVC集成swagger-ui生成 Restful风格的API文档，可以省略手动编写接口文档的过程，也解决了接口变化需要维护接口文档的过程。

swagger-ui还可以测试spring restful风格的接口功能。

官方网站为：http://swagger.io/ 

二、Swagger与Spring MVC集成步骤

1.Maven的配置

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

2. 复制swagger的相关js等静态资源到webapp目录

三、常见swagger注解与使用

Swagger注解使用网址: http://docs.swagger.io/swagger-core/apidocs/

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段

四. 使用描述及效果展示:

@RestController
@Api(value = "User API", description = "会员相关操作")
public class UserController {
    @Autowired
    private UserService userService;

    @Login
    @RequestMapping(value = "/user/login", method = RequestMethod.POST)
    @ApiOperation(httpMethod = "POST", notes = "登录接口", value="登录接口")
    public ResponseEntity<Object> login(@ApiParam(value="登录信息", name="loginParam", required=true)  @RequestBody LoginParam loginParam) {
        Result<UserVO> result = userService.login(loginParam.getEmail(), loginParam.getPassword());
        if (null != result && result.getStatus() == StatusCodes.OK) {// 登录成功
                    WebRuntimeContextHolder.getRuntimeContext().setUser((UserVO) result.getItems());
            return ResponseBuilder.instance().body(null).build();
        } else {
            return ResponseBuilder.instance().body(result).build();
        }
    }

@ApiModel
public class Entity implements java.io.Serializable{

private static final long serialVersionUID = -473540900271240716L;

private Long id;
@ApiModelProperty(required=true)
private Integer logicalDel;
@ApiModelProperty(required=true)
private Date createTime;
@ApiModelProperty(required=true)
private Date updateTime;