今天完成对项目中某个子模块的RESTful
的设计,使用swaggerapi/swagger-editor
工具完成的。完成设计以后,想让团队中的后端和前端开发同事能够很方便的看到设计的成果,并以此作为前后端协作开发依据之一。但是服务器部署swagger-ui
工具并访问本地文件时遇到一个很扯的问题:swagger-ui
官方指导文档介绍的让swagger-ui
读取本地的文件的方式不可行,根本访问不到本地文件。
哎,还是要自力更生呢~~~
1 解决思路
通过查看swagger-ui
官方文档,可以了解到swagger-ui
是基于nginx
来实现部署的。nginx
熟悉啊,能够找到nginx
对应的静态文件目录,然后把设计导出的文件放进去,是不是就可以放了吗?话不多数,开干~~
主要的思路就是:先用运行一个swagger-ui
的容器,然后访问它,查看nginx
静态文件的存放目录,然后将文件拷贝进去,刷新页面重试。
- 运行
swagger-ui
容器
$ docker run -idt -p 8081:8080 --name swagger-ui swaggerapi/swagger-ui
- 访问容器
$ docker exec -it swagger-ui /bin/sh
- 查找
nginx
静态文件位置
$ find / -name nginx.conf
# /etc/nginx/nginx.conf
$ cat /etc/nginx/nginx.conf
worker_processes 1;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
gzip on;
gzip_static on;
gzip_disable "msie6";
gzip_vary on;
gzip_types text/plain text/css application/javascript;
map $request_method $access_control_max_age {
OPTIONS 1728000; # 20 days
}
server_tokens off; # Hide Nginx version
server {
listen 8080;
server_name localhost;
index index.html index.htm;
location / {
absolute_redirect off;
alias /usr/share/nginx/html/;
expires 1d;
location ~* \.(?:json|yml|yaml)$ {
#SWAGGER_ROOT
expires -1;
include cors.conf;
}
include cors.conf;
}
}
}
可以看到nginx
静态文件目录在/usr/share/nginx/html
目录下,使用命令exit
退出当前容器
- 拷贝文件到容器目录中
$ docker cp <target_file_path> swagger-ui:/usr/shar/nginx/html/
- 刷新页面,在输入框中输入文件名称就可以访问了。
2 使用docker-compose改造
上面的解决方式相对繁琐一些,一个是需要敲的命令有点多,另外一个,在本机上完成RESTful
的设计,然后拷贝到服务器上,最后拷贝到镜像中。这里呢,使用docker-compose
对这个过程进行优化,优化的目的,一个是将上述docker
容器操作流程自动化,另一个是在容器上挂载服务器的一个目录,只需将设计好的文件放到这个目录中即可。
docker-compose
文件内容:
version: "3.4"
services:
desktop:
image: swaggerapi/swagger-ui
container_name: swagger-ui
ports:
- "8082:8080"
volumes:
- D:\01-Data\02-LearnNote:/usr/share/nginx/html/swagger
编写好了以后,执行docker-compose up -d
即可自动创建容器,并完成挂载。
在这个文件中,我是在html
目录下创建一个swagger
文件夹,然后将宿主机的文件夹挂载到这个位置,所以,在访问设计文件时,需要在前面加上swagger/
。注意,不能直接挂载到html
文件夹,否则会导致容器启动不成功,因为这样会把html文件夹中的文件替换成挂载文件夹的内容。
贴一张最终的效果图~~~