WSO2 AM API文档问询：能否在DevPortal中使用Swagger作为API文档？

方案1：上传Swagger文件直接关联API（最简便） #

• 用Swagger/OpenAPI规范写完API定义后（支持JSON或YAML格式），直接在WSO2 APIM Publisher控制台创建/编辑API时，选择Import OpenAPI选项，上传你写好的Swagger文件
• 系统会自动解析Swagger中的接口定义、参数、返回值、错误码等内容，同步生成DevPortal上的基础API文档
• 后续如果更新Swagger内容，只需要在Publisher后台重新上传覆盖即可，DevPortal的内容会自动同步

方案2：在DevPortal自定义文档区域嵌入Swagger UI #

如果你们还需要保留自定义编写的文档，同时单独展示可交互的Swagger调试页面，可以使用该方案：

• 首先把你写好的Swagger/OpenAPI规范文件上传到WSO2 APIM的资源存储目录，或者公司内部的静态资源服务
• 在Publisher后台的API Documentation模块，新增一个文档类型为Inline Content的自定义文档
• 在内容编辑框中插入Swagger UI的渲染代码，指定读取你上传的Swagger文件路径即可，发布后DevPortal的对应API文档页就会出现可交互的Swagger调试界面

提示：WSO2 APIM 3.x及以上版本默认已经内置Swagger UI相关依赖，不需要额外引入前端资源，直接调用内置渲染方法即可。

注意事项 #

• 上传Swagger文件时需要注意版本兼容，WSO2 APIM目前支持OpenAPI 2.0（Swagger）、OpenAPI 3.0、OpenAPI 3.1三个版本的规范
• 如果你的Swagger文件中有自定义扩展字段，需要提前在WSO2 APIM的配置项中开启扩展字段解析开关，避免内容丢失
• 所有通过Swagger同步的文档内容，都会自动适配WSO2 DevPortal的权限控制，只有拥有API访问权限的内部用户才能查看，符合内部集成API的使用场景

内容的提问来源于stack exchange，提问作者Lucas Ribeiro