什么是Swagger

Swagger是一款开源工具,依据OpenAPI规范(OpenAPI Specification, 简称 OAS)可帮助你设计, 构建, 生成文档,调用REST APIs.

Swagger优点

1. 最流行的API框架

整合

使用 swagger ui .

创建SpringBoot项目

选择web、lombok、mysql、spring data spa / mybatis, 创建Spring boot项目.在 pom 文件中添加 druid 依赖

<dependencies>
  <dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-starter</artifactId>
    <version>1.1.10</version>
  </dependency>
</dependencies>

创建Restful风格的API

添加Swagger2

添加相关jar包

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

开启 Swagger

Swagger2 在 springboot 框架中使用需要开启 @EnableSwagger2, 同时它支持自定义ui页面的一些信息

@SpringBootApplication
@EnableSwagger2
public class RestApplication{
  public static void main(String[] args){
    SpringApplication.run(RestApplication.class);
  }
}

配置Swagger2

创建swagger配置文件

package com.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Cofiguration;
import springfox.documnetation.builders.ApiInfoBuilder;

@Configuration
public class Swagger2 implements WebMvcConfigurer{
  @Bean
  public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(
    new ApiInfoBuilder()
      // 联系方式
      .contact(new Contact("author","author url","author@email.com"))
      // 标题
      .title("api doc title")
      .build()
    )
  }
}

如上配置后,即可通过http://localhost:8080/swagger-ui/index.html 访问文档首页

Swagger2 常用注解

@RestController
@RequestMapping("/users")
@Api(tags = "控制层描述")
public class UserController{

  @GetMapping("")
  @ApiOperation("接口描述")
  public Response<List<User>> selectAllUsers(){
    // todo: query all matching users
  }
  @GetMapping("{id}")
  @ApiOperation("接口描述")
  @ApiImplicitParam(name = "id", value = "用户标识", required = true, defaultValue = "")
  public Response<User> findUserById(@PathVariable("id") int id){
    // todo: query user by id
  }

  @PostMapping("")
  @ApiOperation("接口描述")
  // 通过在模型User添加注解,生成文档信息
  public Response<User> addUser(User user){
    // todo: add a new user
  }
}

// user model
@Data
@NoArgsConstructor
@AllArgsConstructor
@ToString
@Accessors(chain = true)
@ApiModel("用户模型")
public class User{
  @Id
  @GeneratedValue(strategy=GenerationType.IDENTITY)
  @ApiModelProperty(name="id", value="用户ID", example="1")
  private int id;

  @ApiModelProperty(name="uname", value="用户名", required=true)
  private String uname;

  @ApiModelProperty(name="age", value="用户年龄", required=true)
  private int age;
}