Swagger and OpenAPI #167
Description
swagger是一个API文档和在线测试工具. 可以把API的文档说明写在swagger.json或swagger.yaml文件中, 这个文件可以被渲染成一个漂亮的页面.
这个json文件的格式就是swagger specification. 定义: https://swagger.io/specification/
目前的swagger specification版本号为2.0.
下一个release, Swagger Specification 3.0被重命名成了OpenAPI Specification. 可以认为OpenAPI和Swagger是等价的, 或者认为Swagger是OpenAPI的一个实现.
生成这个json文件的方法很多种, 比如Swagger Editor, IBM API Connect, 在java里边还可以通过写Annotation的方式辅助生成json.
Liberty中的swagger
IBM Liberty集成了Swagger, 打开Feature apiDiscovery-1.0即可(这个feature需要单独安装)
装好后. 启动Liberty时控制台会打印出下面的URL
http://192.168.31.118:9080/api/explorer/
http://192.168.31.118:9080/ibm/api/
http://192.168.31.118:9080/ibm/api/explorer/
http://192.168.31.118:9080/ibm/api/docs/subscription/websocket/
http://192.168.31.118:9080/api/docs/
/ibm/api/explorer/ => IBM内置的swagger UI,
/api/docs/ => 原始的swagger.json文件
可以直接将写好的swagger.json放在META-INF/stub目录下, Liberty会自动渲染这个文件. 如果Liberty开启了basic auth需要, 在json或yaml中加上如下配置:
---
swagger: '2.0'
securityDefinitions:
basicAuth:
type: basic
description: HTTP Basic Authentication.使用java annotation的方式
将swagger-annotations-1.5.17.jar加到classpath (发现Liberty已经集成了这个jar包)
然后参考这里给API加个注解(只需关注以@Api开头的)
References
What Is the Difference Between Swagger and OpenAPI?
Modelling OpenAPI – Swagger 2.0 Specification using API Connect
https://developer.ibm.com/wasdev/blog/2016/02/17/exposing-liberty-rest-apis-swagger/