容器部署 Swagger API 服务

使用容器部署 Swagger API 服务，并支持多个 json 文件切换。

API 格式

• https://github.com/OAI/OpenAPI-Specification
• swagger 在线编辑器
  • 支持导出为 typescript-axios 代理
• OpenAPI Generator 从 OpenAPI 2.0/3.x 文档生成客户端、服务器和文档
• 关键字
  • Deprecated 标记接口已废弃

使用

docker pull swaggerapi/swagger-ui:v3.35.2

docker run -d -p 8080:8080 \
  --name swagger-ui \
  #-e BASE_URL=/swagger \
  #-e SWAGGER_JSON=/foo/swagger.json \
  #-v /data/swagger:/foo \
  -e URLS="[ { url: \"http://petstore.swagger.io/v2/swagger.json\", name: \"Petstore-1\" }, { url: \"http://petstore.swagger.io/v2/swagger.json\", name: \"Petstore-2\" } ]" \
  -e SUPPORTED_SUBMIT_METHODS=['get', 'post', 'put', 'delete'] \
  swaggerapi/swagger-ui:v3.35.2

说明：

• BASE_URL 访问 url 的 subpath
• 访问 http://localhost:8080/?urls.primaryName=Petstore-2 即是 Petstore-2 对应的 json 文件
• 使用 -e PORT 8081 指定端口

进入容器：

docker exec -it swagger-ui sh

相关目录：

• /etc/nginx/conf.d
• /usr/share/nginx/html

Tools

• https://openapi-generator.tech/
• https://swagger.io/tools/swagger-codegen/
• https://openapi.tools/#sdk
• swagger-api/swagger-codegen 生成各种语言 SDK 代码工具
• deepmap/oapi-codegen

swagger 转 markdown

参考 syroegkin/swagger-markdown 将 swagger.yaml 转化为 Markdown 文档

# 安装
npm install -g swagger-markdown

# 使用
swagger-markdown -i path/to/swagger.yaml

类似的其他工具：

• rmariuzzo/markdown-swagger
• Mermade/widdershins

FAQ

跨域问题

修改 Nginx 配置文件后重启容器：

server {
    ...

    location / {
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
        add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Sinc
        ...