使用go-swagger为golang API自动生成swagger文档

什么是swagger？

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

swagger文档长啥样？

一个最简单的swagger文档示例：

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths: {}
复制代码

Tips:阅读本文前提是假设你已经了解了如何编写swagger文档，当然，如果还不了解也没关系，可以去swagger官网查看文档进行学习，并且这里还有一套《Swagger从入门到精通》附上.

本文背景介绍

​ 写作本文的原因是因为公司要求api文档都使用 swagger格式，项目是用golang编写的，作为一个懒癌程序员，怎么能够忍受去编写这么复杂的swagger文档呢？有没有一键生成的工具呢？google一下，还真有,那就是go-swagger项目。go-swagger众多特色功能之一就是Generate a spec from source,即通过源码生成文档，很符合我的需求。

下面就简单介绍下如何为项目加上swagger注释，然后一键生成API文档

开始之前需要安装两个工具：

• swagger-editor:用于编写swagger文档，UI展示，生成代码等...
• go-swagger:用于一键生成API文档

安装swagger-editor,我这里使用docker运行，其他安装方式，请查看官方文档：

docker pull swaggerapi/swagger-editor
docker run --rm -p 80:8080 swaggerapi/swagger-editor
复制代码

安装go-swagger,我这边使用brew安装，其他安装方式，请查看