Docker容器化部署Swagger三件套:Editor、Codegen、UI

说到Swagger就不得不说OpenAPI Specification（OAS），这两个之间存在千丝万缕的联系，不过也不必在意这些细节（主要是我也搞不清），就需要明白

1. OAS是一个规范；
2. Swagger是遵从这个规范的一个工具集之一；
3. OAS目前版本为3.0.3；
4. OAS规范是用来将RESTFul风格的API更容易被计算机和人类理解的，从这个意义上来说和高级编程语言很像；
5. 常用的Swagger组件包括：
   
   
   
   

Swagger Editor	开源	本地、SaaS	基于浏览器的API文档编辑器
Swagger Codegen	开源	本地、SaaS	生成服务端、客户端代码
Swagger UI	开源	本地、SaaS	交互式API文档渲染器
SwaggerHub	免费、收费	SaaS	集成上述三个工具的功能

Editor中包含有Codegen功能
Editor、Codegen、UI都提供Docker方式部署

Swagger Editor安装

>>> docker pull swaggerapi/swagger-editor
>>> docker run -d -p 80:8080 swaggerapi/swagger-editor

http://127.0.0.1

参考：https://github.com/swagger-api/swagger-editor

Swagger Codegen安装(区分OpenAPI 2.0 3.0)

web api官方镜像

仅支持OpenAPI 2.0

# OpenAPI 2.0
>>> docker pull swaggerapi/swagger-generator
>>> docker run -d -e GENERATOR_HOST=http://0.0.0.0 -p 80:8080 swaggerapi/swagger-generator
# OpenAPI 3.0 (运行失败)
>>> docker pull swaggerapi/swagger-generator
>>> docker run -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3
APP_DIR: /generator
Starting application with command: 
/usr/lib/jvm/java-1.8-openjdk/jre/bin/java -Djetty.http.port=80 -DHIDDEN_OPTIONS_PATH= -DHIDDEN_OPTIONS= -server -Duser.timezone=GMT -Xms1024m -Xmx1024m -XX:NewSize=128m -XX:MaxNewSize=128m -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:PermSize=128m -XX:MaxPermSize=128m -Dfile.encoding=UTF-8 -jar /jetty_home/start.jar
OpenJDK 64-Bit Server VM warning: ignoring option PermSize=128m; support was removed in 8.0
OpenJDK 64-Bit Server VM warning: ignoring option MaxPermSize=128m; support was removed in 8.0
java.nio.file.AccessDeniedException: /jetty_home/lib/shared/.mount_navicaS5FMhR
	at sun.nio.fs.UnixException.translateToIOException(UnixException.java:84)
	at sun.nio.fs.UnixException.rethrowAsIOException(UnixException.java:102)
	at sun.nio.fs.UnixException.rethrowAsIOException(UnixException.java:107)
	at sun.nio.fs.UnixFileAttributeViews$Basic.readAttributes(UnixFileAttributeViews.java:55)
	at sun.nio.fs.UnixFileSystemProvider.readAttributes(UnixFileSystemProvider.java:144)
	at sun.nio.fs.LinuxFileSystemProvider.readAttributes(LinuxFileSystemProvider.java:99)
	at java.nio.file.Files.readAttributes(Files.java:1737)
	at java.nio.file.FileTreeWalker.getAttributes(FileTreeWalker.java:225)
	at java.nio.file.FileTreeWalker.visit(FileTreeWalker.java:276)
	at java.nio.file.FileTreeWalker.next(FileTreeWalker.java:372)
	at java.nio.file.Files.walkFileTree(Files.java:2706)
	at org.eclipse.jetty.start.BaseHome.getPaths(BaseHome.java:397)
	at org.eclipse.jetty.start.StartArgs.expandModules(StartArgs.java:523)
	at org.eclipse.jetty.start.Main.processCommandLine(Main.java:351)
	at org.eclipse.jetty.start.Main.main(Main.java:75)
java.nio.file.AccessDeniedException: /jetty_home/lib/shared/.mount_navicaS5FMhR
	at sun.nio.fs.UnixException.translateToIOException(UnixException.java:84)
	at sun.nio.fs.UnixException.rethrowAsIOException(UnixException.java:102)
	at sun.nio.fs.UnixException.rethrowAsIOException(UnixException.java:107)
	at sun.nio.fs.UnixFileAttributeViews$Basic.readAttributes(UnixFileAttributeViews.java:55)
	at sun.nio.fs.UnixFileSystemProvider.readAttributes(UnixFileSystemProvider.java:144)
	at sun.nio.fs.LinuxFileSystemProvider.readAttributes(LinuxFileSystemProvider.java:99)
	at java.nio.file.Files.readAttributes(Files.java:1737)
	at java.nio.file.FileTreeWalker.getAttributes(FileTreeWalker.java:225)
	at java.nio.file.FileTreeWalker.visit(FileTreeWalker.java:276)
	at java.nio.file.FileTreeWalker.next(FileTreeWalker.java:372)
	at java.nio.file.Files.walkFileTree(Files.java:2706)
	at org.eclipse.jetty.start.BaseHome.getPaths(BaseHome.java:397)
	at org.eclipse.jetty.start.StartArgs.expandModules(StartArgs.java:523)
	at org.eclipse.jetty.start.Main.processCommandLine(Main.java:351)
	at org.eclipse.jetty.start.Main.main(Main.java:75)

Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
       java -jar $JETTY_HOME/start.jar --help  # for more information

http://127.0.0.1

本地生成失败！！！

使用官方提供的服务生成正常

原因不明
bug太多所以不推荐这种方法

CLI官方镜像

# OpenAPI 2.0
>>> docker pull swaggerapi/swagger-codegen-cli
>>>  docker run --rm -v ${PWD}/Downloads:/Downloads swaggerapi/swagger-codegen-cli generate \
     -i /Downloads/openapi.json \
     -l python \
     -o /Downloads/python
# OpenAPI 3.0
>>> docker pull swaggerapi/swagger-codegen-cli-v3
>>>  docker run --rm -v ${PWD}/Downloads:/Downloads swaggerapi/swagger-codegen-cli-v3 generate \
     -i /Downloads/openapi.json \
     -l python \
     -o /Downloads/python

参考：https://github.com/swagger-api/swagger-codegen

Swagger UI安装

>>> docker pull swaggerapi/swagger-ui
>>> docker run -p 80:8080 -e SWAGGER_JSON=/foo/microfat-test-1.0.0-resolved.json -v ~/Downloads:/foo swaggerapi/swagger-ui

http://127.0.0.1

参考：https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md