swagger 返回json字符串_解析和增量导出 Swagger 的 JSON 文件

用了 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()