swagger2离线⽂档⽂档中⼼搭建jsonswagger⾃动⽣成api⽂
档
最近了⼀个⾃动⽣成api⽂档的⼯具swagger，相对swaggerEdit就不说了。个⼈⽐较懒，还是⾃动⽣成来的便捷，尤其是⽼项⽬，新项
⽬在初期可能会维护，但是到了后期就很难保证了。所以，那些需要⼀些特殊配置说明的⽂档⼯具就不提了。
这篇⽂章主要是在swagger2 swagger UI的基础上结合nginx解决跨域来实现统⼀的api⽂档中⼼，⾄于如何搭建swagger2请⾃⾏百度。
使⽤swagger2⽣成离线⽂档⽐较⿇烦，尤其是⾮springcloud项⽬（具体实现⽅式，请⾃⾏百度）。本⽂另辟蹊径，通过修改swagger部分js脚本⽂件、提供统⼀的资源加载路径、使⽤nginx反向代理解决swagger测试跨域问题，来搭建⼀个统⼀的api⽂档中⼼系统。
⾸先说⼀下swagger的jar包：
其他⾃⾏百度，主要说⼀下swagger的请求流程：
swaggerUI的静态⽂件：
springfox-swagger-ui-2.6.1.jar 解压缩打开后在META-INF\resources下⾯就可以看到我们访问的html页以及静态⽂件。
swagger2的⼏个资源服务controller:
swagger-resources//configuration/security
swagger-resources/configuration/ui：控制页⾯展⽰效果
swagger-resources/：⽐较重要，这个也是我们要覆盖重写的主要协议
所在jar包：springfox-swagger-common-2.6.1.jar
controller类路径： springfox.documentation.swagger.web.ApiResourceController
最重要的代码路径，⽣成api⽂档的服务：
jar包：springfox-swagger2-2.6.1.jar
controller类路径：springfox.documentation.swagger2.web.Swagger2Controller
我们要搭建中⼼api⽂档，或者离线⽂档，那就需要更改js⽂件，把资源路径修改为统⼀的服务路径或者静态json（访问/v2/api-docs可以获取接⼝描述json）⽂件。
贴代码：重
写swagger-resources服务和提供统⼀的api-docs⽂档(swagger-resources提供的location就是⽣成接⼝描述页⾯数据的来源访问路径)：
@RequestMapping("my")
@RestController
public class SwaggerController {
private static Logger logger = Logger(SwaggerController.class);
private static Map<String,SwaggerResource> resourceMap = new HashMap<String,SwaggerResource>();
public static void getDocJson(){
String filename = "apidoc.json";
Type type =new TypeToken<Map<String,SwaggerResource>>(){}.getType();
resourceMap = new Gson().fromJson(
new InputStreamReader(ClassLoader().getResourceAsStream(filename),Charset.forName("UTF-8")),type);
}
static{
getDocJson();
}
@RequestMapping("/swagger-resources")
public ResponseEntity<List<SwaggerResource>> swaggerResources() {
public ResponseEntity<List<SwaggerResource>> swaggerResources() {
getDocJson();
List<SwaggerResource> swaggerResources = new ArrayList<SwaggerResource>();
if(resourceMap!=null&&resourceMap.size()>0){
for (String key : resourceMap.keySet()) {
SwaggerResource resource = (key);
swaggerResources.add(resource);
if(StringUtils.Location())){
resource.setLocation("/my/apidoc/"+key);
}
}
}
/*SwaggerResource resource = new SwaggerResource();
resource.setName("default");
resource.setLocation("/v2/api-docs");
resource.setSwaggerVersion("2.0");
swaggerResources.add(resource);
resource = new SwaggerResource();
resource.setName("本地⽂件");
resource.setLocation("/apidoc/Goods_0.0.1.json");
resource.setSwaggerVersion("0.0.1");
swaggerResources.add(resource);
resource = new SwaggerResource();
resource.setName("远程测试");
resource.setLocation("127.0.0.1/Goods_0.0.1.json");
resource.setSwaggerVersion("0.0.1");
swaggerResources.add(resource);*/
return new ResponseEntity<List<SwaggerResource>>(swaggerResources, HttpStatus.OK);
}
@RequestMapping("/apidoc/{id}")
public String findJsonDocs1(@PathVariable("id")String id) {
SwaggerResource resource = (id);
String swagger = "";
if(StringUtils.Path())){
RestTemplate template = new RestTemplate();
ResponseEntity<String> body = Path(), HttpMethod.GET, null, String.class);
try {
return new Body().getBytes("iso8859-1"),"utf-8");
} catch (UnsupportedEncodingException e) {
<("远程获取数据转码异常(findJsonDocs1):", e);
}
}else if(StringUtils.FileName())){
try {
InputStreamReader in = new InputStreamReader(ClassLoader().FileName()),Charset.forName BufferedReader reader = new BufferedReader(in);
String tmp = null;
StringBuilder sb = new StringBuilder();
while((tmp = adLine()) != null){
sb.append(tmp);
}
swagger = sb.toString();
} catch (IOException e) {
<("读取⽂件异常(findJsonDocs1):", e);
}
return swagger;
}
JSONString( new Swagger());
}
}
提供的配置⽂件：apidoc.json
{
"1":{"name":"default","location":"/v2/api-docs","swaggerVersion":"2.0","host":"localhost:8080/","path":"","fileName":""},
"2":{"name":"本地⽂件","location":"","swaggerVersion":"2.0","host":"localhost:8080","path":"","fileName":"Goods_0.0.1.json"},
"3":{"name":"远程⽂件","location":"","swaggerVersion":"2.0","host":"127.0.0.1","path":"127.
0.0.1/Goods_0.0.1.json","fileName":""} }
其中，path表⽰远程http协议路径，fileName表⽰本地资源⽂件路径。
对应的Bean实体类：
public class SwaggerResource extends springfox.documentation.swagger.web.SwaggerResource{
/**
* 域名端⼝
*/
private String host;
/**
* 远程资源路径
*/
private String path;
/**
js获取json的key和value* 本地资源
*/
private String fileName;
public String getHost() {
return host;
}
public void setHost(String host) {
this.host = host;
}
public String getPath() {
return path;
}
public void setPath(String path) {
this.path = path;
}
public String getFileName() {
return fileName;
}
public void setFileName(String fileName) {
this.fileName = fileName;
}
}
贴⼀下改写的js⽂件：springfox.js：
function initializeBaseUrl() {
var relativeLocation = springfox.baseUrl();
$('#input_baseUrl').hide();
$.getJSON(relativeLocation + "/my/swagger-resources", function(data) {
var $urlDropdown = $('#select_baseUrl');
$pty();
$.each(data, function(i, resource) {
var option = $('<option></option>')
.
attr("value", maybePrefix(resource.location, relativeLocation))
.text(resource.name + " (" + resource.location + ")");
$urlDropdown.append(option);
});
$urlDropdown.change();
});
}
这是springfox.js的最后⼀个函数(initializeBaseUrl)，如果是搭建中⼼的api⽂档系统，更改/swagger-resources路径为我们⾃定义的服务路径/my/swagger-resources即可。
如果是搭建离线的⽂档，讲这部分代码改写成访问静态资源⽂件就可以了。
/swagger-resources数据格式：
[{"name":"default","location":"/v2/api-docs","swaggerVersion":"2.0"}]
效果图：
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论