一、什么是Swagger

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

二、配置

依赖

  1. <!--Swagger-UI API文档生产工具-->
  2. <dependency>
  3.   <groupId>io.springfox</groupId>
  4.   <artifactId>springfox-swagger2</artifactId>
  5.   <version>2.7.0</version>
  6. </dependency>
  7. <dependency>
  8.   <groupId>io.springfox</groupId>
  9.   <artifactId>springfox-swagger-ui</artifactId>
  10.   <version>2.7.0</version>
  11. </dependency>

添加配置类

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //为当前包下controller生成API文档
//            .apis(RequestHandlerSelectors.basePackage("com.example.test.controller"))
            //为有@Api注解的Controller生成API文档
            .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            //为有@ApiOperation注解的方法生成API文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("用户管理系统")
            .description("用户管理系统API文档")
            .contact("xiaoyu")
            .version("1.0")
            .build();
    }
}

如果需要为指定的包下所有的控制器生成文档，使用：

...

.apis(RequestHandlerSelectors.basePackage("com.example.test.controller"))

如果只需要为添加了 @Api 和 @ApiOperation 注解的控制器方法添加文档，使用：

...

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

三、常用注解

  • @Api 用于修饰Controller类，生成Controller相关文档信息
  • @ApiOperation 用于修饰Controller类中的方法，生成接口方法相关文档信息
  • @ApiParam 用于修饰接口中的参数，生成接口参数相关文档信息
  • @ApiModelProperty 用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

四、在控制器中使用

@Api(tags = "UserController", description = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    UserRepository userRepository;

    @ApiOperation("获取所有用户列表")
    @GetMapping("/all")
    public List<User> findAll() {
        return userRepository.findAll();
    }
}

访问接口地址：http://localhost:8080/swagger-ui.html
001.webp

五、在模型中使用

通过在模型字段中添加 @ApiModelProperty 注解，可以为文档添加字段描述

@Data
@AllArgsConstructor
@NoArgsConstructor
@Entity(name = "user")
public class User {
    private static final long serialVersionUID = 1L;

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "密码")
    private String password;
}

控制器：

  @ApiOperation("添加用户")
  @GetMapping("/create")
  public User create(@PathVariable User user) {
      return userRepository.save(user);
  }

效果：
002.webp
003.webp

参考资料