swagger教程详解

一、什么是swagger？

Swagger是一个由Swagger API工具集支持的开放源代码软件框架，它主要有以下三个功能：

1. 定义API元数据（标题、版本、许可证、作者等）

2. 描述API的安全性和身份验证方案

3. 描述API生成文档

因此，Swagger是一种能够根据API定义自动生成API文档的工具，让API文档更加一致和易于理解。

二、如何使用swagger？

使用swagger很简单，首先需要在使用的前端框架中加入相应的依赖。

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

然后需要在Spring Boot应用程序中配置Swagger。

    @EnableSwagger2
    @SpringBootApplication
    public class Application {
        public static void main(String[] args) {
            SpringApplication.run(Application.class, args);
        }
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(apiInfo());
        }
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("API文档")
                    .description("这是一份描述API的文档！")
                    .version("1.0.0")
                    .build();
        }
    }

然后就可以在浏览器中访问http://localhost:8080/swagger-ui.html来查看Swagger生成的API文档了。

三、Swagger常用注解

Swagger提供了很多注解，常用的注解如下：

1. @Api：用于描述整个API文档信息。

2. @ApiOperation：用于描述一个API操作。

3. @ApiParam：用于描述一个参数。

4. @ApiModel：用于描述一个POJO类。

5. @ApiModelProperty：用于描述一个POJO类的属性。

例如：

    @Api(tags = "User", description = "UserController相关的接口")
    @RestController
    public class UserController {
        
        @ApiOperation(value = "创建用户", notes = "根据传过来的User对象来创建用户")
        @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
        @PostMapping("/user")
        public String createUser(@RequestBody User user) {
            return "success";
        }
        
        @ApiModel(value = "用户实体", description = "用户实体user")
        public class User {
            @ApiModelProperty(value = "用户名", example = "tom")
            private String name;
            @ApiModelProperty(value = "年龄", example = "18")
            private Integer age;
            //其他属性省略
        }
    }

四、Swagger高级用法

Swagger还提供了一些高级用法，例如：

1. 给API添加Header信息：

    @ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "token", value = "Token", required = true, dataType = "string", paramType = "header")
    })
    @GetMapping("/user")
    public String getUserInfo(Integer id) {
        return "user info";
    }

2. 给API添加响应状态码：

    @ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功!"),
            @ApiResponse(code = 400, message = "请求参数错误"),
            @ApiResponse(code = 401, message = "未授权"),
            @ApiResponse(code = 404, message = "请求地址不存在"),
            @ApiResponse(code = 500, message = "服务器内部错误")
    })
    @GetMapping("/user")
    public String getUserInfo(Integer id) {
        return "user info";
    }

五、Swagger的优点

通过使用Swagger，API文档和API定义可以被统一维护和更新，API的使用者可以方便快捷地查阅和使用API。

同时，设计API时，可以通过Swagger来保证API的正确性和规范性，避免API定义不规范、不一致等问题。