• Index

关于作者

关注公众号不定期领红包:

关注微博获取实时动态:

集成Open API

Reads: 2617 Edit

Open API是一个标准,它的主要作用是描述REST API,既可以作为文档给开发者阅读,又可以让机器根据这个文档自动生成客户端代码等。

在Spring Boot应用中,假设我们编写了一堆REST API,如何添加Open API的支持?

我们只需要在pom.xml中加入以下依赖:

org.springdoc:springdoc-openapi-ui:1.4.0

然后呢?没有然后了,直接启动应用,打开浏览器输入http://localhost:8080/swagger-ui.html

swagger-ui

立刻可以看到自动生成的API文档,这里列出了3个API,来自api-controller(因为定义在ApiController这个类中),点击某个API还可以交互,即输入API参数,点“Try it out”按钮,获得运行结果。

是不是太方便了!

因为我们引入springdoc-openapi-ui这个依赖后,它自动引入Swagger UI用来创建API文档。可以给API加入一些描述信息,例如:

@RestController
@RequestMapping("/api")
public class ApiController {
    ...
    @Operation(summary = "Get specific user object by it's id.")
	@GetMapping("/users/{id}")
	public User user(@Parameter(description = "id of the user.") @PathVariable("id") long id) {
		return userService.getUserById(id);
	}
    ...
}

@Operation可以对API进行描述,@Parameter可以对参数进行描述,它们的目的是用于生成API文档的描述信息。添加了描述的API文档如下:

api-description

大多数情况下,不需要任何配置,我们就直接得到了一个运行时动态生成的可交互的API文档,该API文档总是和代码保持同步,大大简化了文档的编写工作。

要自定义文档的样式、控制某些API显示等,请参考springdoc文档

练习

利用springdoc实现API文档

小结

使用springdoc让其自动创建API文档非常容易,引入依赖后无需任何配置即可访问交互式API文档。

可以对API添加注解以便生成更详细的描述。


Comments

Make a comment

  • Index