From de00b56d9af00d5223d32f8d99fc12a232145764 Mon Sep 17 00:00:00 2001 From: Patrick Connolly Date: Mon, 5 Nov 2018 01:58:09 +0800 Subject: [PATCH] Added loose docs for each endpoint. --- bridge/api/api.go | 22 +++++++- docs/docs.go | 115 ++++++++++++++++++++++++++++++++++++-- docs/swagger/swagger.json | 113 +++++++++++++++++++++++++++++++++++-- docs/swagger/swagger.yaml | 73 +++++++++++++++++++++++- 4 files changed, 309 insertions(+), 14 deletions(-) diff --git a/bridge/api/api.go b/bridge/api/api.go index 7dcc1b03..74ef46cc 100644 --- a/bridge/api/api.go +++ b/bridge/api/api.go @@ -16,13 +16,12 @@ import ( ) // @title Matterbridge API -// @version TODO // @description A read/write API for the Matterbridge chat bridge. // @license.name Apache 2.0 // @license.url https://github.com/42wim/matterbridge/blob/master/LICENSE -// @host TODO +// TODO @host // @basePath /api type API struct { @@ -39,6 +38,9 @@ type Message struct { Gateway string `json:"gateway"` } +// @securityDefinitions.apikey +// @in header +// @name Authorization func New(cfg *bridge.Config) bridge.Bridger { b := &API{Config: cfg} e := echo.New() @@ -102,6 +104,12 @@ func (b *Api) handleDocsRedirect(c echo.Context) error { return c.Redirect(http.StatusMovedPermanently, "/swagger/index.html") } +// handlePostMessage godoc +// @Summary Create/Update a message +// @Accept json +// @Produce json +// @Success 200 {object} config.Message +// @Router /message [post] func (b *API) handlePostMessage(c echo.Context) error { message := config.Message{} if err := c.Bind(&message); err != nil { @@ -118,6 +126,11 @@ func (b *API) handlePostMessage(c echo.Context) error { return c.JSON(http.StatusOK, message) } +// handleMessages godoc +// @Summary Lists messages +// @Produce json +// @Success 200 {array} config.Message +// @Router /messages [get] func (b *API) handleMessages(c echo.Context) error { b.Lock() defer b.Unlock() @@ -126,6 +139,11 @@ func (b *API) handleMessages(c echo.Context) error { return nil } +// handleStream godoc +// @Summary Streams realtime messages +// @Produce json +// @Success 200 {object} config.Message +// @Router /stream [get] func (b *API) handleStream(c echo.Context) error { c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationJSON) c.Response().WriteHeader(http.StatusOK) diff --git a/docs/docs.go b/docs/docs.go index a44bfe53..ad880f50 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -1,6 +1,6 @@ // GENERATED BY THE COMMAND ABOVE; DO NOT EDIT // This file was generated by swaggo/swag at -// 2018-11-04 21:12:10.529569 +0800 CST m=+0.079119212 +// 2018-11-05 01:51:14.853722 +0800 CST m=+0.078800065 package docs @@ -17,12 +17,117 @@ var doc = `{ "license": { "name": "Apache 2.0", "url": "https://github.com/42wim/matterbridge/blob/master/LICENSE" - }, - "version": "TODO" + } }, - "host": "TODO", "basePath": "/api", - "paths": {} + "paths": { + "/message": { + "post": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "summary": "Create/Update a message", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "$ref": "#/definitions/config.Message" + } + } + } + } + }, + "/messages": { + "get": { + "produces": [ + "application/json" + ], + "summary": "Lists messages", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/config.Message" + } + } + } + } + } + }, + "/stream": { + "get": { + "produces": [ + "application/json" + ], + "summary": "Streams realtime messages", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "$ref": "#/definitions/config.Message" + } + } + } + } + } + }, + "definitions": { + "config.Message": { + "type": "object", + "properties": { + "account": { + "type": "string" + }, + "avatar": { + "type": "string" + }, + "channel": { + "type": "string" + }, + "event": { + "type": "string" + }, + "extra": { + "type": "object" + }, + "gateway": { + "type": "string" + }, + "id": { + "type": "string" + }, + "protocol": { + "type": "string" + }, + "text": { + "type": "string" + }, + "timestamp": { + "type": "string" + }, + "userid": { + "type": "string" + }, + "username": { + "type": "string" + } + } + } + }, + "securityDefinitions": { + "": { + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } }` type s struct{} diff --git a/docs/swagger/swagger.json b/docs/swagger/swagger.json index 56c0bf6b..ad2840e2 100644 --- a/docs/swagger/swagger.json +++ b/docs/swagger/swagger.json @@ -7,10 +7,115 @@ "license": { "name": "Apache 2.0", "url": "https://github.com/42wim/matterbridge/blob/master/LICENSE" - }, - "version": "TODO" + } }, - "host": "TODO", "basePath": "/api", - "paths": {} + "paths": { + "/message": { + "post": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "summary": "Create/Update a message", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "$ref": "#/definitions/config.Message" + } + } + } + } + }, + "/messages": { + "get": { + "produces": [ + "application/json" + ], + "summary": "Lists messages", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/config.Message" + } + } + } + } + } + }, + "/stream": { + "get": { + "produces": [ + "application/json" + ], + "summary": "Streams realtime messages", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "$ref": "#/definitions/config.Message" + } + } + } + } + } + }, + "definitions": { + "config.Message": { + "type": "object", + "properties": { + "account": { + "type": "string" + }, + "avatar": { + "type": "string" + }, + "channel": { + "type": "string" + }, + "event": { + "type": "string" + }, + "extra": { + "type": "object" + }, + "gateway": { + "type": "string" + }, + "id": { + "type": "string" + }, + "protocol": { + "type": "string" + }, + "text": { + "type": "string" + }, + "timestamp": { + "type": "string" + }, + "userid": { + "type": "string" + }, + "username": { + "type": "string" + } + } + } + }, + "securityDefinitions": { + "": { + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + } } \ No newline at end of file diff --git a/docs/swagger/swagger.yaml b/docs/swagger/swagger.yaml index cbe8736d..6c83409b 100644 --- a/docs/swagger/swagger.yaml +++ b/docs/swagger/swagger.yaml @@ -1,5 +1,32 @@ basePath: /api -host: TODO +definitions: + config.Message: + properties: + account: + type: string + avatar: + type: string + channel: + type: string + event: + type: string + extra: + type: object + gateway: + type: string + id: + type: string + protocol: + type: string + text: + type: string + timestamp: + type: string + userid: + type: string + username: + type: string + type: object info: contact: {} description: A read/write API for the Matterbridge chat bridge. @@ -7,6 +34,46 @@ info: name: Apache 2.0 url: https://github.com/42wim/matterbridge/blob/master/LICENSE title: Matterbridge API - version: TODO -paths: {} +paths: + /message: + post: + consumes: + - application/json + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/config.Message' + type: object + summary: Create/Update a message + /messages: + get: + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/config.Message' + type: array + summary: Lists messages + /stream: + get: + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/config.Message' + type: object + summary: Streams realtime messages +securityDefinitions: + "": + in: header + name: Authorization + type: apiKey swagger: "2.0"