Swagger UI使用介绍

1 Swagger简介

swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
作用：
1.接口文档自动在线生成。
2.功能测试。
Swagger是一组开源项目，其中主要项目如下：
1.Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger1.2文档转换成Swagger2.0文档等功能。
2.Swagger-core：用于Java/Scala的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…）、Servlets和Play框架进行集成。
3.Swagger-js：用于JavaScript的Swagger实现。
4.Swagger-node-express：Swagger模块，用于node.js的Express web应用框架。
5.Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
6.Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

2 Maven

可根据实际情况修改版本号

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

3 创建Swagger配置类

创建Swagger配置类SwaggerConfiguration

/**
 * Swagger配置
 */

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggertest.api"))
                .paths(PathSelectors.any())
                .build()
                ;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description(
                        "<div>&nbsp;</div>" +
                                "<div>&nbsp;</div>" +
                                "<div>接口说明</div>" +
                                "<div>&nbsp;</div>" +
                                "<div>&nbsp;</div>" 
                                "<div>&nbsp;</div>"
                )
                .version("1.0")
                .build();
    }
}

4 添加文档内容

Swagger使用的注解及其说明：
@Api：用在类上，说明该类的作用。
@ApiOperation：注释来给API增加方法说明。
@ApiImplicitParams：用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应。
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
| code：数字，例如400
| message：信息，例如“请求参数没填好”
| response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用于在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性

@ApiImplicitParam的参数说明如下：

示例：

@Api(description = "系统用户相关接口", tags = ApiIndex.UserController)
@RequestMapping(value = "/api/user")
@RestController
public class UserController {
    @Autowired
    IUserService service;

	@ApiOperation(value = "查询列表")
    @GetMapping(value = "/list")
    @ApiImplicitParam(name = "token", value = "签名", paramType = "query", dataType = "String")
    @Token
    public R<PageInfo<List<UserVO>>> list(
            @ApiParam(value = "查询参数") @ModelAttribute UserSearchVO searchVO) {
        List<UserVO> list = service.getList(searchVO);
        PageInfo pageInfo = new PageInfo(list);
        return new R(pageInfo);
    }
} 

完成上述代码，启动springboot程序，访问http://localhost:8080/swagger-ui.html