SpringBoot中使用Swagger

Swagger是一个用于构建生成Restful API文档的开源框架，主要包括以下工具集：

• Swagger Core Java相关类库，生成以及处理Swagger的定义规范
• Swagger Editor 使用YAMl格式编写Swagger脚本
• Swagger Codegen 针对各种语言的SDK，用于生成文档
• Swagger UI 基于HTML5的可交互的UI

Springfox是基于Swagger的Api文档生成工具，对SpringMvc支持很好，在Springboot中可以使用Springfox生成在线Api文档

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

配置类，指定扫描路径以及显示内容

@Configuration
@EnableSwagger2
@Profile("dev")
//@ComponentScan
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                .build()
                .globalResponseMessage(RequestMethod.GET,
                        Lists.newArrayList(new ResponseMessageBuilder().code(500).message("500 ERROR").build()));
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("用户管理系统")
                .description("Restful API文档")
                .contact(new Contact("admin","http://xxx.zz.com", "admin@email.com"))
                .version("1.0")
                .build();

        return apiInfo;
    }
}

在Controller中使用Swagger注解

@Api(value="用户管理",tags = {"用户管理API"},description = "描述信息")
@Controller
public class UserController {

    @ApiOperation(value = "添加用户", notes = "添加用户notes", produces = "application/json")
    @ResponseBody
    @RequestMapping(value= "/user", method = RequestMethod.POST)
    public UserResult user(@ApiParam(value="用户参数") @RequestBody UserParam param) {
        UserResult userResult = new UserResult();
        userResult.setId("Hello" + param.getName());
        userResult.setAge(param.getAge());
        return userResult;
    }

    @ApiOperation("查询用户")
    @ApiImplicitParams({
        @ApiImplicitParam(name="name",value="用户名",dataType = "string",paramType = "query")
    })
    @ResponseBody
    @RequestMapping(value = "/user", method = RequestMethod.GET)
    public UserResult user(HttpServletRequest req) {
        String name = req.getParameter("name");
        UserResult userResult = new UserResult();
        userResult.setId("Hello" + name);
        userResult.setAge(100);
        return userResult;
    }

    @ApiOperation("获取用户")
    @ResponseBody
    @RequestMapping(value= "/user/{name}", method = RequestMethod.GET)
    @ApiResponses(value={
            @ApiResponse(code=123,message="xxx"),
            @ApiResponse(code=405,message="not found")
    })
    public UserResult user(@ApiParam(value = "用户名") @PathVariable("name") String name, @RequestParam("query") String query) {
        UserResult userResult = new UserResult();
        userResult.setId("Hello" + name);
        userResult.setAge(100);
        return userResult;
    }
}

请求参数实体，可使用ApiModel以及ApiModelProperty

@ApiModel(value="用户参数", description = "用户参数描述")
public class UserParam {

    @ApiModelProperty(value="用户名", required = true)
    private String name;
    private Integer age;
    
     ...// set get
}

返回内容对象

@ApiModel
public class UserResult {

    @ApiModelProperty(name="yyy",value="xxx")
    private String id;
    private Integer age;
    
    ... 
}

访问Swagger Api： http://localhost:8080/swagger-ui.html

Swagger常用注解：

• @Api 标识Controller使用swagger.
• @ApiImplicitParam 表示一个隐式的请求参数，即请求方法中没有显示绑定参数名称.
• @ApiImplicitParams 表示隐式参数列表.
• @ApiModel 描述请求或返回对象的额外信息.
• @ApiModelProperty 描述或者生成ApiModel的成员变量.
• @ApiOperation 描述一个Http请求方法
• @ApiParam 描述显示的请求参数.
• @ApiResponse 描述可能的返回对象.
• @ApiResponses 表示返回对象列表.
• @Authorization 申明认证信息.
• @ResponseHeader 表示返回头部信息.

相关文档：

1. http://springfox.github.io/springfox/docs/current/#springfox-samples
2. https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#api