From 35907df52e11175a30aa08da171163b5eff47725 Mon Sep 17 00:00:00 2001 From: Raman <24293550+ramank775@users.noreply.github.com> Date: Sat, 16 Apr 2022 18:17:23 +0530 Subject: [PATCH] Added Open api spec document (#67) * Added api docs link and postman collection * Added open api spec docs --- README.md | 13 ++- docs/openapi.yaml | 274 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 286 insertions(+), 1 deletion(-) create mode 100644 docs/openapi.yaml diff --git a/README.md b/README.md index 6b7d52d..51bc2a3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # Chat Server [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md) - [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ramank775/chat-server) A chat server based on the microservice architecture to ensure high availability, high throughput, horizontal scalability using Kafka @@ -167,12 +166,24 @@ Click on the Gitpod badge it will start the fully setup development environment. ## Deployment For deployment guide refer to [deployment/README.md](./deployment/README.md). + # Resources + +## API specs doc +[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/20439391-376454b4-ccc4-4fb5-8b88-5a3a3392e6d1?action=collection%2Ffork&collection-url=entityId%3D20439391-376454b4-ccc4-4fb5-8b88-5a3a3392e6d1%26entityType%3Dcollection%26workspaceId%3Def561179-c2db-47e5-85ce-10440f20555c) + +- API documentation [here](https://documenter.getpostman.com/view/20439391/Uyr5neME) + +- Open API specs 3.0 [here](./docs/openapi.yaml) + +## Blog posts To follow the update keep a eye on vartalap blogs on [blog.one9x.org](https://blog.one9x.org) Some of the relevent blogs are: - [Vartalap: Open Source Personal Messaging App](https://blog.one9x.org/vartalap/2021/04/04/vartalap-personal-messaging-app.html) - [Vartalap: Chat Server Architecture V1](https://blog.one9x.org/vartalap/2021/04/10/vartalap-chat-server-architecture.html) - [Vartalap: Chat Server Architecture V2](https://blog.one9x.org/vartalap/2021/05/22/vartalap-chat-server-architecture-v2.html) - [Vartalap: Chat Server Architecture V2.1](https://blog.one9x.org/vartalap/2021/06/26/vartalap-chat-server-architecture-v2-1.html) + + ## LICENSE [MIT](./LICENSE) diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 0000000..bb70d51 --- /dev/null +++ b/docs/openapi.yaml @@ -0,0 +1,274 @@ +openapi: 3.0.0 +info: + title: Vartalap + version: 1.0.0 +servers: + - url: http://{{baseurl}} +tags: + - name: Auth + description: Authentication endpoints + - name: Profile + description: User Profile Endpoints + - name: Gateway + description: >- + Web socket and HTTP Gateway + + As open api spec doesn't yet support adding web socket specs + + Endpoint: `wss://{{hostname}}/wss` + - name: Group + description: Endpoints for performing group related actions + - name: File + description: File service endpoint to upload and download files +paths: + /login: + post: + tags: + - Auth + summary: Login With Firebase + description: Authenticate with Firebase such as Phone Auth + requestBody: + content: + application/json: + schema: + type: object + example: + username: '{{username}}' + notificationToken: fcm token + parameters: + - name: token + in: header + schema: + type: string + description: Firebase auth token + example: '{{firebase_auth_token}}' + responses: + '200': + description: Successful response + content: + application/json: {} + /profile/get: + get: + tags: + - Profile + summary: Get Profile + description: Get User profile + responses: + '200': + description: Successful response + content: + application/json: {} + /profile/user/sync: + post: + tags: + - Profile + summary: Sync Contact + description: Sync contact book, to fetch list of users using this service + requestBody: + content: + application/json: + schema: + type: object + example: + users: + - username_1 + - username_2 + responses: + '200': + description: Successful response + content: + application/json: {} + /messages: + post: + tags: + - Gateway + summary: Send Message + description: Http endpoint to send messages + requestBody: + content: + application/json: + schema: + type: object + example: + - _v: 2 + id: string + head: + type: chat|group|channel|bot|notification + to: username|group_id|channel_id|bot_id + from: username + chatid: chatid + contentType: json|text|video|audio|location|form + action: >- + message|ack|subscribe|unsubscribe|join|leave|create|add-member|remove-member + meta: + hash: md5:hash + content_hash: md5:hash + generate_ts: 123455667890 + body: + text: Hello this a text message + responses: + '200': + description: Successful response + content: + application/json: {} + /group/create: + post: + tags: + - Group + summary: Create New Group + description: Create new group chat + requestBody: + content: + application/json: + schema: + type: object + example: + name: Group Name/Title + profilePic: profile-pic-id + members: + - member_1_username + - member_2_username + responses: + '200': + description: Successful response + content: + application/json: {} + /group/{groupId}/add: + post: + tags: + - Group + summary: Add Members to Group + description: Add members to existing group chat + requestBody: + content: + application/json: + schema: + type: object + example: + members: + - member_3_username + - member_4_username + parameters: + - name: groupId + in: path + schema: + type: string + required: true + responses: + '200': + description: Successful response + content: + application/json: {} + /group/{groupId}/remove: + post: + tags: + - Group + summary: Remove Member From Group + description: >- + Remove other members only valid if you have admin permission or Leave + group chat. + requestBody: + content: + application/json: + schema: + type: object + example: + member: member_1_username + parameters: + - name: groupId + in: path + schema: + type: string + required: true + responses: + '200': + description: Successful response + content: + application/json: {} + /group/{groupId}: + get: + tags: + - Group + summary: Get Group Info + description: Get group chat information including name, display pic, members + parameters: + - name: groupId + in: path + schema: + type: string + required: true + responses: + '200': + description: Successful response + content: + application/json: {} + /group/get: + get: + tags: + - Group + summary: Get All Groups + description: Get All the groups user have access to + responses: + '200': + description: Successful response + content: + application/json: {} + /file/upload/presigned_url: + post: + tags: + - File + summary: Generate Presigned URL for upload + requestBody: + content: + application/json: + schema: + type: object + example: + ext: .png + category: chat + responses: + '200': + description: Successful response + content: + application/json: {} + /file/{fileId}/status: + put: + tags: + - File + summary: Update File Status + requestBody: + content: + application/json: + schema: + type: object + example: + status: true + parameters: + - name: fileId + in: path + schema: + type: string + required: true + example: 62512603033fd6b538e12c72 + responses: + '200': + description: Successful response + content: + application/json: {} + /file/download/{fileId}/presigned_url: + get: + tags: + - File + summary: Get Presigned Url to download file + parameters: + - name: fileId + in: path + schema: + type: string + required: true + example: 62512603033fd6b538e12c72 + responses: + '200': + description: Successful response + content: + application/json: {} \ No newline at end of file