用了 Swagger 的程序在运行时会扫描类和方法里的注解,生成 JSON 文档,默认地址为接口访问地址后面加 /v2/api-docs
本地启动的服务默认为 http://localhost:8080/v2/api-docs
Swagger UI 生成的网页的数据源就是这 JSON 文件
缺点:
只有服务启动了才能查看,没有离线版
只支持全量导出,有些由于历史遗留问题没细分的服务可能有几千个接口,不方便查看
靠 Swagger 配置类里设的分组难以满足 “只看这版本新增接口” 这样的需求
思路
写脚本解析 Swagger 生成的 json 文件,可以干很多事:
对比新旧 2 份文件,分别导出新增、删除的接口
按关键字导出特定接口
修改页面发请求时访问的服务器地址
……
json 文件格式如下,只列出一定会出现的属性:
{
"swagger": "2.0",
"host": "xxx",
"basePath": "/",
"tags":[
{"name":"xxx-controller","description":"xxx"},
...
],
"paths": {
"": { ... },
"": { ... },
...
},
"definitions": {
"": { ... },
"": { ... },
...
}
}
host:服务器域名或 IP
basePath:必须以 / 开头,访问某服务的接口时网关里设的那个前缀。如果 host 指定端口直连,这里为/
tags:默认为 Controller 类名(@Api注解了的类)。建议保持默认,不需要设@Api(tags={"xx", "yy"})或@Api(value="xxx")
paths:接口(@ApiOperation注解了的方法)
definitions:实体类(@ApiModel注解了的类)
其中 host 和 basePath 最重要,这里设置得不对,页面上就没法访问到服务
以下脚本原本打算用于 Confluence 的 Open API 插件,把 json 导出来之后粘贴到插件里就有跟 swagger ui 一样的效果
但那插件非常不方便,后来有了这帖里的集中展示之后就不用那插件了,export_apis 和 export_models 这 2 个方法也显得多余了(当时想着万一还想加 1 个就粘贴文件里的内容插进去)
实现
新建 Python 文件,比如叫做 swagger_json_dump.py
再另外用 Java 搭个 Spring Boot + Swagger 的 demo,看看不同设置下的输出,边调边写,都是体力活
# coding=utf-8
import argparse
import errno
import json
import os
import re
import sys
from datetime import datetime
from os import path
import requests
HOST = 'localhost:8080'
BASE_PATH = '/'
def check_python_version():
if sys.version_info[0] < 3 or (sys.version_info[0] == 3 and sys.version_info[1] < 2):
print('Must use Python 3.2+. Current version:', sys.version)
sys.exit(1)
def parse_cmdline_args():
parser = argparse.ArgumentParser()