Swagger

Swagger

接口编码规范

其中 1、3、4 建议作为接口编码时必须项

// 0、 方法描述
@ApiOperation(value = "getUser", nickname = "getUser")
// 1、 请求类型
@RequestMapping(method = RequestMethod.GET,     // 1-1、 请求方法
        path = "/demo/user",                    // 1-2、 请求URL
        produces = "application/json")          // 1-3、 相应数据类型
// 2、 请求参数描述
@ApiImplicitParams({
        @ApiImplicitParam(name = "name",        // 2-1、 参数名
                required = false,               // 2-3、 是否必须
                dataType = "string",            // 2-4、 数据类型 （类名或基本类型）
                paramType = "query",            // 2-5、 参数类型 （ path, query, body, header, form）
                defaultValue = "Niklas",        // 2-6、 参数默认值
                value = "用户名")                // 2-7、 字段描述
})
// 3、 状态码描述： code 状态码  message 描述  response 返回值类型
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = User.class),
        @ApiResponse(code = 401, message = "Unauthorized"),
        @ApiResponse(code = 403, message = "Forbidden"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 500, message = "Failure")})
public User getUser(
        // 4、 请求参数描述，与2基本相同。可选参数少，但直接对应参数，比较直观。建议使用 4 进行参数描述。
        // Object 类型，需在该对象内设置 @ApiModel @ApiModelProperty 等注解。
        @RequestParam(value = "phone", defaultValue = "15510967745") String phone,
        @RequestParam(value = "status") int status, User testUser) {
    User user = new User();
    user.setPhone(phone);
    user.setEmail(testUser.getEmail());
    user.setPassword(testUser.getPassword());
    user.setStatus(status);
    return user;
}

对象参数注解

@ApiModel(value = "User",                           // 模型名称
        description = "the base info of user",      // 描述
        parent = BaseIdEntity.class)                // 父类
@Table("t_user")
public class User extends BaseIdEntity {
    /**
     * 手机号
     */
    /* 属性描述，常用参数如下：
            value: 参数名描述
            notes: 同value
            dataType: 参数类型
            require: 是否必须
            hidden: 是否在SwaggerJson内显示
    */ 
    @ApiModelProperty(notes = "用户手机号", required = false)
    @Column
    private String phone;
    /**
     * email
     */
    @NotEmpty
    @Column
    @ApiModelProperty(notes = "用户Email", required = true)
    private String email;
    /**
     * 密文密码
     */
    @Column
    @ApiModelProperty(notes = "密文密码", required = false)
    private String password;
    /**
     * 用户是否被屏蔽
     */
    @Column
    @ApiModelProperty(notes = "用户是否被屏蔽", required = false)
    private Integer status;
    // ... getter() & setter() ...
}

『swagger-ui』 界面

访问地址: http://{ipaddress:port}/swagger/index.html