From 110b840d480b07c99ec281568d78367b7566d8e1 Mon Sep 17 00:00:00 2001 From: Patrick Connolly Date: Mon, 5 Nov 2018 04:32:39 +0800 Subject: [PATCH] Updated config.Message API docs. Allow params to be input via swagger ui. --- bridge/api/api.go | 5 ++-- bridge/config/config.go | 34 +++++++++++++++-------- docs/docs.go | 58 ++++++++++++++++++++++++++++++--------- docs/swagger/swagger.json | 56 +++++++++++++++++++++++++++++-------- docs/swagger/swagger.yaml | 43 +++++++++++++++++++++++++++-- 5 files changed, 156 insertions(+), 40 deletions(-) diff --git a/bridge/api/api.go b/bridge/api/api.go index 74ef46cc..e6f584de 100644 --- a/bridge/api/api.go +++ b/bridge/api/api.go @@ -108,6 +108,7 @@ func (b *Api) handleDocsRedirect(c echo.Context) error { // @Summary Create/Update a message // @Accept json // @Produce json +// @Param body body object true "Message object to create" // @Success 200 {object} config.Message // @Router /message [post] func (b *API) handlePostMessage(c echo.Context) error { @@ -127,7 +128,7 @@ func (b *API) handlePostMessage(c echo.Context) error { } // handleMessages godoc -// @Summary Lists messages +// @Summary List of new messages // @Produce json // @Success 200 {array} config.Message // @Router /messages [get] @@ -141,7 +142,7 @@ func (b *API) handleMessages(c echo.Context) error { // handleStream godoc // @Summary Streams realtime messages -// @Produce json +// @Produce json-stream // @Success 200 {object} config.Message // @Router /stream [get] func (b *API) handleStream(c echo.Context) error { diff --git a/bridge/config/config.go b/bridge/config/config.go index eb34912d..92168722 100644 --- a/bridge/config/config.go +++ b/bridge/config/config.go @@ -27,18 +27,30 @@ const ( ) type Message struct { - Text string `json:"text"` - Channel string `json:"channel"` - Username string `json:"username"` - UserID string `json:"userid"` // userid on the bridge - Avatar string `json:"avatar"` - Account string `json:"account"` - Event string `json:"event"` - Protocol string `json:"protocol"` - Gateway string `json:"gateway"` + // Content of the message + Text string `json:"text" example:"Testing, testing, 1-2-3."` + // Human-readable channel name + Channel string `json:"channel" example:"test-channel"` + // Human-readable username + Username string `json:"username" example:"alice"` + // userid on the bridge + UserID string `json:"userid" example:"U4MCXJKNC"` + // URL to an avatar image + Avatar string `json:"avatar" example:"https://secure.gravatar.com/avatar/1234567890abcdef1234567890abcdef.jpg"` + // Unique account name of format "." + Account string `json:"account" example:"slack.myteam"` + // Can be blank. + Event string `json:"event" example:""` + // Chat protocol of incoming message + Protocol string `json:"protocol" example:"slack"` + // Name of the gateway + Gateway string `json:"gateway" example:"test-channel-gateway"` + // Unique ID of a parent message, if threaded ParentID string `json:"parent_id"` - Timestamp time.Time `json:"timestamp"` - ID string `json:"id"` + Timestamp time.Time `json:"timestamp" example:"1541361213.030700"` + // Unique ID of message on the gateway + ID string `json:"id" example:"slack 1541361213.030700"` + // Extra data that doesn't fit in other fields. Used for processing incoming messages. Extra map[string][]interface{} } diff --git a/docs/docs.go b/docs/docs.go index ad880f50..5511ee31 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-05 01:51:14.853722 +0800 CST m=+0.078800065 +// 2018-11-05 04:31:47.316226 +0800 CST m=+0.167027083 package docs @@ -30,6 +30,17 @@ var doc = `{ "application/json" ], "summary": "Create/Update a message", + "parameters": [ + { + "description": "Message object to create", + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object" + } + } + ], "responses": { "200": { "description": "OK", @@ -46,7 +57,7 @@ var doc = `{ "produces": [ "application/json" ], - "summary": "Lists messages", + "summary": "List of new messages", "responses": { "200": { "description": "OK", @@ -63,7 +74,7 @@ var doc = `{ "/stream": { "get": { "produces": [ - "application/json" + "application/x-json-stream" ], "summary": "Streams realtime messages", "responses": { @@ -83,40 +94,61 @@ var doc = `{ "type": "object", "properties": { "account": { - "type": "string" + "description": "Unique account name of format \"\u003cprotocol\u003e.\u003cslug\u003e\"\n", + "type": "string", + "example": "slack.myteam" }, "avatar": { - "type": "string" + "description": "URL to an avatar image\n", + "type": "string", + "example": "https://secure.gravatar.com/avatar/1234567890abcdef1234567890abcdef.jpg" }, "channel": { - "type": "string" + "description": "Human-readable channel name\n", + "type": "string", + "example": "test-channel" }, "event": { + "description": "Can be blank.\n", "type": "string" }, "extra": { + "description": "Extra data that doesn't fit in other fields. Used for processing incoming messages.\n", "type": "object" }, "gateway": { - "type": "string" + "description": "Name of the gateway\n", + "type": "string", + "example": "test-channel-gateway" }, "id": { - "type": "string" + "description": "Unique ID of message on the gateway\n", + "type": "string", + "example": "slack 1541361213.030700" }, "protocol": { - "type": "string" + "description": "Chat protocol of incoming message\n", + "type": "string", + "example": "slack" }, "text": { - "type": "string" + "description": "Content of the message\n", + "type": "string", + "example": "Testing, testing, 1-2-3." }, "timestamp": { - "type": "string" + "type": "string", + "example": "1541361213.030700" }, "userid": { - "type": "string" + "description": "userid on the bridge\n", + "type": "string", + "example": "U4MCXJKNC" }, "username": { - "type": "string" + "description": "Human-readable username\n", + "type": "string", + "example": "alice" } } } diff --git a/docs/swagger/swagger.json b/docs/swagger/swagger.json index ad2840e2..e78e175f 100644 --- a/docs/swagger/swagger.json +++ b/docs/swagger/swagger.json @@ -20,6 +20,17 @@ "application/json" ], "summary": "Create/Update a message", + "parameters": [ + { + "description": "Message object to create", + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object" + } + } + ], "responses": { "200": { "description": "OK", @@ -36,7 +47,7 @@ "produces": [ "application/json" ], - "summary": "Lists messages", + "summary": "List of new messages", "responses": { "200": { "description": "OK", @@ -53,7 +64,7 @@ "/stream": { "get": { "produces": [ - "application/json" + "application/x-json-stream" ], "summary": "Streams realtime messages", "responses": { @@ -73,40 +84,61 @@ "type": "object", "properties": { "account": { - "type": "string" + "description": "Unique account name of format \"\u003cprotocol\u003e.\u003cslug\u003e\"\n", + "type": "string", + "example": "slack.myteam" }, "avatar": { - "type": "string" + "description": "URL to an avatar image\n", + "type": "string", + "example": "https://secure.gravatar.com/avatar/1234567890abcdef1234567890abcdef.jpg" }, "channel": { - "type": "string" + "description": "Human-readable channel name\n", + "type": "string", + "example": "test-channel" }, "event": { + "description": "Can be blank.\n", "type": "string" }, "extra": { + "description": "Extra data that doesn't fit in other fields. Used for processing incoming messages.\n", "type": "object" }, "gateway": { - "type": "string" + "description": "Name of the gateway\n", + "type": "string", + "example": "test-channel-gateway" }, "id": { - "type": "string" + "description": "Unique ID of message on the gateway\n", + "type": "string", + "example": "slack 1541361213.030700" }, "protocol": { - "type": "string" + "description": "Chat protocol of incoming message\n", + "type": "string", + "example": "slack" }, "text": { - "type": "string" + "description": "Content of the message\n", + "type": "string", + "example": "Testing, testing, 1-2-3." }, "timestamp": { - "type": "string" + "type": "string", + "example": "1541361213.030700" }, "userid": { - "type": "string" + "description": "userid on the bridge\n", + "type": "string", + "example": "U4MCXJKNC" }, "username": { - "type": "string" + "description": "Human-readable username\n", + "type": "string", + "example": "alice" } } } diff --git a/docs/swagger/swagger.yaml b/docs/swagger/swagger.yaml index 6c83409b..cced4174 100644 --- a/docs/swagger/swagger.yaml +++ b/docs/swagger/swagger.yaml @@ -3,28 +3,60 @@ definitions: config.Message: properties: account: + description: | + Unique account name of format "." + example: slack.myteam type: string avatar: + description: | + URL to an avatar image + example: https://secure.gravatar.com/avatar/1234567890abcdef1234567890abcdef.jpg type: string channel: + description: | + Human-readable channel name + example: test-channel type: string event: + description: | + Can be blank. type: string extra: + description: | + Extra data that doesn't fit in other fields. Used for processing incoming messages. type: object gateway: + description: | + Name of the gateway + example: test-channel-gateway type: string id: + description: | + Unique ID of message on the gateway + example: slack 1541361213.030700 type: string protocol: + description: | + Chat protocol of incoming message + example: slack type: string text: + description: | + Content of the message + example: Testing, testing, 1-2-3. type: string timestamp: + example: "1541361213.030700" type: string userid: + description: | + userid on the bridge + example: U4MCXJKNC type: string username: + description: | + Human-readable username + example: alice type: string type: object info: @@ -39,6 +71,13 @@ paths: post: consumes: - application/json + parameters: + - description: Message object to create + in: body + name: body + required: true + schema: + type: object produces: - application/json responses: @@ -59,11 +98,11 @@ paths: items: $ref: '#/definitions/config.Message' type: array - summary: Lists messages + summary: List of new messages /stream: get: produces: - - application/json + - application/x-json-stream responses: "200": description: OK