Swagger (#124)

* start experimenting with swagger documentation

* further adventures in swagger

* do a few more api paths

* account paths documented

* go fmt

* fix up some models

* bit o lintin'

cmd/gotosocial/main.go

@@ -16,13 +16,38 @@
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+// Package classification awesome.
+//
+// Documentation of our awesome AaaaaaaaaaPI.
+//
+//     Schemes: http
+//     BasePath: /
+//     Version: 1.0.0
+//     Host: some-url.com
+//
+//     Consumes:
+//     - application/json
+//
+//     Produces:
+//     - application/json
+//
+//     Security:
+//     - basic
+//
+//    SecurityDefinitions:
+//    basic:
+//      type: basic
+//
+// swagger:meta
+
 package main
 
 import (
 	"os"
 
 	"github.com/sirupsen/logrus"
 
+	_ "github.com/superseriousbusiness/gotosocial/docs"
 	"github.com/urfave/cli/v2"
 )
 
@@ -32,6 +57,7 @@ var Version string
 // Commit is the git commit of GtS being used
 var Commit string
 
+//go:generate swagger generate spec
 func main() {
 	var v string
 	if Commit == "" {

docs/api/swagger.md

@@ -0,0 +1,9 @@
+# API Documentation
+
+GoToSocial uses [go-swagger](https://github.com/go-swagger/go-swagger) to generate a V2 [OpenAPI specification](https://swagger.io/specification/v2/) document from code annotations.
+
+The resulting API documentation is rendered below, for quick reference.
+
+If you'd like to do more with the spec, you can also view the [swagger.yaml](/api/swagger/swagger.yaml) directly, and then paste it into something like the [Swagger Editor](https://editor.swagger.io/) in order to autogenerate GoToSocial API clients in different languages, convert the doc to JSON or OpenAPI v3 specification, etc. See [here](https://swagger.io/tools/open-source/getting-started/) for more.
+
+!!swagger swagger.yaml!!