"swagger 接口服务是我本机,如果我下班关机回家,对方如何进行联调?"

如果你有类似的疑问,这篇文章可以帮助你。

项目源码地址: github

背景

出于稳定性考虑,在提测前不允许发布到测试环境,开发阶段如何保障 swagger 接口的稳定性?

方案


actor java_producer_coder
actor java_consumer_coder
actor js_consumer_coder

cloud {
    control nginx
    node "swagger-ui" AS swagger #green
    node "swagger-json" AS json
}

java_consumer_coder --> swagger
js_consumer_coder --> swagger
swagger -right-> nginx
nginx -down-> json
java_producer_coder -up-> json: push 接口json 文件

s0

  1. 搭建 swagger-ui 服务
  2. nginx 划分静态目录 (swagger-json),并允许跨域
  3. 接口 owner 将 swagger json 文件上传至 nginx 静态目录 (swagger-json)

在安装了 docker 的机器,通过run.sh可以执行镜像 build 及容器运行。

实现

docker 搭建 swagger-ui 服务

Dockerfile

from swaggerapi/swagger-ui

docker 搭建 swagger-json 服务

就是一个nginx服务,提供了 http 访问 json 的能力。

Dockerfile

FROM nginx

COPY ./conf/nginx.conf /etc/nginx/nginx.conf
COPY ./static/*.json /usr/share/nginx/html/

nginx.conf中配置跨域操作Access-Control-Allow-Origin *

user  nginx;
worker_processes  1;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    add_header Access-Control-Allow-Origin *;
     add_header Access-Control-Allow-Headers X-Requested-With;
     add_header Access-Control-Allow-Methods GET,POST,OPTIONS;

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf;
}

static目录下是接口 json 文件

发布接口

通过 http://localhost:8080/v2/api-docs 获取 json 文件,命名后 push 到 git 项目api目录下

访问 swagger

浏览器访问 swagger-ui 服务,并在窗口输入 json 文件访问路径 https://localhost:8080/demo_api_2.json ,然后就可以看到 swagger 接口定义。

s1

优化

看了一下swagger-ui的镜像实现,内部也是一个 nginx,运行 js。所以没必要自己搞一套 nginx,直接把 json 文件 copy 到swagger-ui即可。

更新后到 swagger 服务 Dockerfile 如下

from swaggerapi/swagger-ui

ENV API_URL=http://localhost:8080/demo_api_1.json

#ENV API_URLS="[{url:'http://localhost:8080/demo_api_1.json', name :' 接口一 '}, {url:'http://localhost:8080/demo_api_2.json', name :' 接口二 '}]"

COPY ./api/*.json /usr/share/nginx/html/

缺陷

  1. 不能根据代码动态更新,需要 owner 手动 push 接口 json 文件。
  2. 需要手动输入 json 访问 url。

关于缺陷 2可以考虑使用API_URLS环境变量实现,但是设置后,不能自定义输入 jsonUrl

from swaggerapi/swagger-ui

ENV API_URLS="[{url:'http://localhost:8080/demo_api_1.json', name :' 接口一 '}, {url:'http://localhost:8080/demo_api_2.json', name :' 接口二 '}]"

COPY ./api/*.json /usr/share/nginx/html/

效果图如下
s2

  • Swagger

    Swagger 是一款非常流行的 API 开发工具,它遵循 OpenAPI Specification(这是一种通用的、和编程语言无关的 API 描述规范)。Swagger 贯穿整个 API 生命周期,如 API 的设计、编写文档、测试和部署。

    11 引用 • 13 回帖 • 4 关注
  • Java

    Java 是一种可以撰写跨平台应用软件的面向对象的程序设计语言,是由 Sun Microsystems 公司于 1995 年 5 月推出的。Java 技术具有卓越的通用性、高效性、平台移植性和安全性。

    2332 引用 • 6786 回帖 • 1182 关注
  • API
    31 引用 • 241 回帖 • 1 关注
感谢    关注    收藏    赞同    反对    举报    分享