goswagger入门手册

March 30, 2019

本文旨在记录使用goswagger过程中遇到的一些问题（只在生成文档方面，不涉及其他功能）：

• 如何在go1.11+以上（支持Go Module）版本中的应用swagger
• 一些注解上的注意事项
• 如何在团队中管理API文档（主要涵盖了：swagger-ui的部署和使用）

关于swagger #

swagger涵盖WebAPI的一整套工具：API设计，API实现（代码生成），API文档，API测试及API规范。更多信息请参见官网

准备工作 #

• 一个Golang web项目，并软连接到GOPATH/src下。【毕竟是支持Gomodule的项目，还放在GOPATH下就不科学了😄】
• 安装swagger工具. 参见安装
• 环境：

  ➜  swagger-demo git:(master) ✗ go version
  go version go1.11.5 darwin/amd64
  ➜  swagger-demo git:(master) ✗ swagger version
  version: v0.18.0
  commit: 6b23bb61413826ce42c3b14a37bf5870caf91e0b
  

编写注释 #

元信息包含了这个应用的基本信息。一般新建一个doc.go放在你的API根目录下；还有一定要注意这句话：

You give it a main file and it will parse all the files that are reachable by that main package to produce a swagger specification.To use you can add a go:generate comment to your main file。

...