写在前面

      作为刚入门运维的一员,接到了一个任务,在docker中部署swagger。对于swagger自己进行后端开发的时候也是接触到了,那会对于他的理解是可以用来管理接口,我们写的方法都会在swagger中显示出来,我们也可以在swagger上进行测试。接到这个任务的时候,我想也是我要对他的理解再进一点的时候了。

      官网的解释:Swagger是面向OpenAPI规范(OAS)的API开发人员工具的世界上最大的框架,可以在整个API生命周期中进行开发,从设计和文档到测试和部署。

      自己理解:我们开发的契约,当前端和后端分离的时候,我们依据swagger上提供的api进行开发,我们共同遵循这同一个契约。利用在线的swagger我们只需要一个json文件,或xml文件加上swagger自己封装的接口我们就可以模拟真实的功能。


部署

      why?为什么要本地部署呢?最近做项目网络总是不给力,一个页面要加载好长时间,于是我们项目组长先发制人要大家本地的swagger。

环境

  • 运行docker容器的服务器

镜像

      下载所需要的镜像,这些不是必要的操作,方便我们之后的查看。

docker pull swaggerapi/swagger-ui
docker pull swaggerapi/swagger-editor

引入项目

      官网上有本地搭建服务器的文件,我们可以拿下来直接用,这是链接:https://github.com/swagger-api/swagger-ui,我们将整个文件夹拉到服务器上。

dockerfile构建镜像

      在这个文件夹下我们会看到一个dockerfile的文件,我们的镜像也是通过dockerfile来构建的。下面对dockerfile的内容进行简单的说明如下:

FROM alpine:3.5

MAINTAINER fehguy

ENV VERSION "v2.2.10"
ENV FOLDER "swagger-ui-2.2.10"

#默认swagger启动加载的json文件,需要修改成自己的ip地址+json文件
ENV API_URL "http://petstore.swagger.io/v2/swagger.json" 
ENV API_KEY "**None**"
ENV OAUTH_CLIENT_ID "**None**"
ENV OAUTH_CLIENT_SECRET "**None**"
ENV OAUTH_REALM "**None**"
ENV OAUTH_APP_NAME "**None**"
ENV OAUTH_ADDITIONAL_PARAMS "**None**"
ENV SWAGGER_JSON "/app/swagger.json"
ENV PORT 80

RUN apk add --update nginx
RUN mkdir -p /run/nginx

COPY nginx.conf /etc/nginx/

# copy swagger files to the `/js` folder
#这些需要手动添加,将dist下面的文件复制到该目录下,为什么要这样呢?先思考
#将docker-run.sh复制到该目录下
ADD ./dist/* /usr/share/nginx/html/
ADD ./docker-run.sh /usr/share/nginx/

EXPOSE 8080

#启动nginx
CMD ["sh", "/usr/share/nginx/docker-run.sh"]

      dockerfile中提到把dist文件复制到/usr/share/nginx/html/,这是为什么呢?我们看一下nginx的配置文件便会清楚很多了~

location / {
      root    /usr/share/nginx/html;
      index   index.html index.htm;
      }

      进入到我们down下来的文件中,构建镜像;

//swagger-ui-builder为名字,可以自定义
//.是根目录,不要忽略哦~
docker build -t swagger-ui-builder .

启动容器

      镜像是只读的,静态的,我们要把镜像运行起来才可操作,如何运行起来呢,着就要说道容器了,我们run 一个镜像的容器,便可以读写了,当然我们操作的结果并不会对镜像改变什么,我们变动是容器,我们可以这样理解:容器=镜像+可读写层。以下是启动命令:

docker run --name=swagger-ui-bulder -p 8080:8080 -d  镜像ID

维护

      运维的一定要想到后续是如何维护的,不然只会增加工作难度和时间,日后修改json文件,我们将更新后的文件放到dist下面,同时更新dockerfile的URL,最后重新构建镜像。

访问

      在浏览器中输入ip地址就可以访问了,如下图:
这里写图片描述


持续

      这块目前有一个遗留问题,我们本地搭起来swagger框架,可以查看api,但是根据path访问某个方法是还是不通,我想这里是用到了反射,这只是猜想,接下来就是去验证了,还是要不断修炼和研究。

      遇到问题,解决问题。相信我们的办法总比困难多啊,加油~

Logo

权威|前沿|技术|干货|国内首个API全生命周期开发者社区

更多推荐