SpringBoot集成Swagger-Knife4j生成美化RESTful API文档

首先创建一个SpringBoot项目，我这里使用的SpringBoot 2.7.8版本的

在pom.xml里面引入springfox和knife4j的依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>3.0.3</version>
</dependency>

创建实体类，添加相关注解

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户基本信息")
public class User {

    @ApiModelProperty(value = "ID", required = true, example = "1")
    private Long id;

    @ApiModelProperty(value = "姓名", required = true, example = "百彦子烨")
    private String name;

    @ApiModelProperty(value = "年龄", required = true, example = "21")
    private Integer age;

}

创建控制层，添加相关注解

@Api(tags="用户管理")
@RestController
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    /**
     * 处理"/users"的GET请求，用来获取用户列表
     *
     * @return
     */
    @ApiOperation("获取用户列表")
    @GetMapping("/users")
    public List<User> getUserList() {
        // 还可以通过@RequestParam从页面中传递参数来进行查询条件或者翻页信息的传递
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    /**
     * 处理"/users"的POST请求，用来创建User
     *
     * @param user
     * @return
     */
    @ApiOperation("创建用户")
    @PostMapping("/users")
    public String postUser(@RequestBody User user) {
        // @RequestBody注解用来绑定通过http请求中application/json类型上传的数据
        users.put(user.getId(), user);
        return "success";
    }

    /**
     * 处理"/users/{id}"的GET请求，用来获取url中id值的User信息
     *
     * @param id
     * @return
     */
    @ApiOperation("获取指定ID的用户信息")
    @GetMapping("/users/{id}")
    public User getUser(@PathVariable Long id) {
        // url中的id可通过@PathVariable绑定到函数的参数中
        return users.get(id);
    }

    /**
     * 处理"/users/{id}"的PUT请求，用来更新User信息
     *
     * @param id
     * @param user
     * @return
     */
    @ApiOperation("更新用户信息")
    @PutMapping("/users/{id}")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    /**
     * 处理"/users/{id}"的DELETE请求，用来删除User
     *
     * @param id
     * @return
     */
    @ApiOperation("删除用户")
    @DeleteMapping("/users/{id}")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }
}

在application.properties中更改端口（也可不改，默认8080）

开启Swagger

server.port=8087

swagger.enabled=true

启动项目，在浏览器访问该地址

http://localhost:8087/doc.html

即可看到生成的文档页面，可以在线对接口进行调试

SpringBoot集成Swagger-Knife4j生成美化RESTful API文档

猜你喜欢