Swagger 简单使用

步骤

安装 Maven 依赖包

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

配置 Swagger 2

@Configuration
@EnableSwagger2 // 启用Swagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）
                .apis(RequestHandlerSelectors.basePackage("com.engure.testhttps.controller"))
                .paths(PathSelectors.any())
                .build();

        // token 验证
    }

    // 创建该Api的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 中使用 Swagger2 构建 RESTful APIs")
                .description("我是 ApiInfo 描述")
                .contact(new Contact("Engure", "https://baidu.com", "engureguo@qq.com"))
                .version("1.0")
                .build();
    }

}

配置接口

实体类

@Data
public class User {
    private Long id;
    private Integer age;
    private String name;
}

在接口上添加注解

@RestController
@RequestMapping(value = "/users")     // 配置 URL 前缀
public class UserController {

    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    //指定 <接口、操作概述value、说明信息notes>
    @GetMapping
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
    public List<User> getUserList() {
        System.out.println(users.values());
        return new ArrayList<>(users.values());
    }

    /**
     * 向后台传递 json 对象。 @ApiImplicitParam + @RequestBody 配合
     */
    @PostMapping
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @PutMapping
    @ApiOperation(value = "更新用户详细信息", notes = "根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    public String putUser(@RequestBody User user) {
        User u = users.get(user.getId());
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(user.getId(), u);
        return "success";
    }

    /**
     * 使用路径变量，其中 @ApiImplicitParam 的 paramType 指定参数类型为 path（有 body, query, path, form 四种！）
     */
    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "long", paramType = "path")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "long", paramType = "path")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

参考

• swagger2的常用注解，传递参数的注意使用方法 https://www.cnblogs.com/fengli9998/p/7921601.html