From 1569a81894b75a8e4ec481ea94e6148b090882f5 Mon Sep 17 00:00:00 2001 From: Dimitri Gilbert Date: Wed, 24 Jan 2018 10:44:52 +0100 Subject: Basic api documentation #7 (#220) * Basic api documentation * fix styling issue * fix styling issue * gitignore unecessary folders * openApi 2.0 first draft * solved conflicts * solved errors in openapi file * added missing doc on video + deleted apidoc comments * fix last warnings and errors inopenapi definition --- openapi.yaml | 1209 ++++++++++++++++++++++++++++++ server/controllers/api/server/follows.ts | 1 - 2 files changed, 1209 insertions(+), 1 deletion(-) create mode 100644 openapi.yaml diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 000000000..e6d2f51d8 --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,1209 @@ +swagger: '2.0' +info: + title: peertube + version: 0.0.13-alpha + description: Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with WebTorrent and Angular. +paths: + '/accounts/{id}': + get: + tags: + - Accounts + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The id of the account' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/Account' + /accounts: + get: + tags: + - Accounts + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Account' + /config: + get: + tags: + - Config + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/ServerConfig' + /jobs: + get: + tags: + - Job + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Job' + '/server/following/{host}': + delete: + tags: + - ServerFollowing + consumes: + - application/json + produces: + - application/json + parameters: + - name: host + in: path + required: true + type: string + description: 'The host to unfollow ' + responses: + '201': + description: successful operation + /server/followers: + get: + tags: + - ServerFollowing + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Follow' + /server/following: + get: + tags: + - ServerFollowing + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Follow' + post: + tags: + - ServerFollowing + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + schema: + $ref: '#/definitions/Follow' + responses: + '204': + description: successful operation + /users: + post: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + schema: + $ref: '#/definitions/AddUser' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/AddUserResponse' + get: + tags: + - User + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/User' + '/users/{id}': + delete: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The user id ' + responses: + '204': + description: successful operation + get: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The user id ' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/User' + put: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The user id ' + - in: body + name: body + required: true + schema: + $ref: '#/definitions/UpdateUser' + responses: + '204': + description: successful operation + /users/me: + get: + tags: + - User + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/User' + put: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + schema: + $ref: '#/definitions/UpdateMe' + responses: + '204': + description: successful operation + /users/me/video-quota-used: + get: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: successful operation + schema: + type: number + '/users/me/videos/{videoId}/rating': + get: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/GetMeVideoRating' + /users/me/videos: + get: + tags: + - User + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Video' + /users/register: + post: + tags: + - User + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + required: true + schema: + $ref: '#/definitions/RegisterUser' + responses: + '204': + description: successful operation + /users/me/avatar/pick: + post: + tags: + - User + consumes: + - multipart/form-data + produces: + - application/json + parameters: + - in: formData + name: avatarfile + type: file + description: The file to upload. + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/Avatar' + /video: + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Video' + /video/categories: + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + type: string + /video/licences: + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + type: string + /video/languages: + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + type: string + /video/privacies: + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + type: string + /video/search: + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/Video' + "/video/{id}": + put: + tags: + - Video + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/Video' + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/Video' + delete: + tags: + - Video + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation + "/video/{id}/description": + get: + tags: + - Video + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + schema: + type: string + "/video/{id}/views": + post: + tags: + - Video + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation + /video/upload: + post: + tags: + - Video + consumes: + - multipart/form-data + produces: + - application/json + parameters: + - in: formData + name: videofile + type: file + description: The file to upload. + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/VideoUploadResponse' + /video/abuse: + get: + tags: + - VideoAbuse + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/VideoAbuse' + "/video/{id}/abuse": + post: + tags: + - VideoAbuse + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation + "/video/{videoId}/blacklist": + post: + tags: + - VideoBlacklist + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation + delete: + tags: + - VideoBlacklist + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation + /video/blacklist: + get: + tags: + - VideoBlacklist + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/VideoBlacklist' + /video/channels: + get: + tags: + - VideoChannel + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/VideoChannel' + post: + tags: + - VideoChannel + consumes: + - application/json + produces: + - application/json + parameters: + - in: body + name: body + schema: + $ref: '#/definitions/VideoChannelInput' + responses: + '204': + description: successful operation + "/video/channels/{id}": + get: + tags: + - VideoChannel + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + schema: + $ref: '#/definitions/VideoChannel' + put: + tags: + - VideoChannel + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + - in: body + name: body + schema: + $ref: '#/definitions/VideoChannelInput' + responses: + '204': + description: successful operation + delete: + tags: + - VideoChannel + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation + /video/accounts/{accountId}/channels: + get: + tags: + - VideoChannel + consumes: + - application/json + produces: + - application/json + parameters: + - name: accountId + in: path + required: true + type: string + description: 'The account id ' + responses: + '200': + description: successful operation + schema: + type: array + items: + $ref: '#/definitions/VideoChannel' + "/video/{videoId}/comment-threads": + get: + tags: + - VideoComment + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + post: + tags: + - VideoComment + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + responses: + '200': + description: successful operation + "/video/{videoId}/comment-threads/{threadId}": + get: + tags: + - VideoComment + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + - name: threadId + in: path + required: true + type: string + description: 'The thread id ' + responses: + '200': + description: successful operation + "/video/{videoId}/comments/{commentId}": + post: + tags: + - VideoComment + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + - name: commentId + in: path + required: true + type: string + description: 'The comment id ' + responses: + '200': + description: successful operation + delete: + tags: + - VideoComment + consumes: + - application/json + produces: + - application/json + parameters: + - name: videoId + in: path + required: true + type: string + description: 'The video id ' + - name: commentId + in: path + required: true + type: string + description: 'The comment id ' + responses: + '204': + description: successful operation + "/video/{id}/rate": + put: + tags: + - VideoRate + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: path + required: true + type: string + description: 'The video id ' + responses: + '204': + description: successful operation +definitions: + Video: + properties: + id: + type: number + uuid: + type: string + accountName: + type: string + createdAt: + type: string + updatedAt: + type: string + categoryLabel: + type: string + category: + type: number + licenceLabel: + type: string + licence: + type: number + languageLabel: + type: string + language: + type: number + description: + type: string + duration: + type: number + isLocal: + type: boolean + name: + type: string + serverHost: + type: string + thumbnailPath: + type: string + previewPath: + type: string + embedPath: + type: string + views: + type: number + likes: + type: number + dislikes: + type: number + nsfw: + type: boolean + VideoAbuse: + properties: + id: + type: number + reason: + type: string + reporterUsername: + type: string + reporterServerHost: + type: string + videoId: + type: number + videoUUID: + type: string + videoName: + type: string + createdAt: + type: string + VideoBlacklist: + properties: + id: + type: number + videoId: + type: number + createdAt: + type: string + updatedAt: + type: string + name: + type: string + uuid: + type: string + description: + type: string + duration: + type: number + views: + type: number + likes: + type: number + dislikes: + type: number + nsfw: + type: boolean + VideoChannel: + properties: + displayName: + type: string + description: + type: string + isLocal: + type: boolean + owner: + type: object + properties: + name: + type: string + uuid: + type: string + videos: + type: array + items: + $ref: "#/definitions/Video" + VideoComment: + properties: + id: + type: number + url: + type: string + text: + type: string + threadId: + type: number + inReplyToCommentId: + type: number + videoId: + type: number + createdAt: + type: string + updatedAt: + type: string + totalReplies: + type: number + account: + $ref: "#/definitions/Account" + Avatar: + properties: + path: + type: string + createdAt: + type: string + updatedAt: + type: string + Actor: + properties: + id: + type: number + uuid: + type: string + url: + type: string + name: + type: string + host: + type: string + followingCount: + type: number + followersCount: + type: number + createdAt: + type: string + updatedAt: + type: string + avatar: + $ref: "#/definitions/Avatar" + Account: + allOf: + - $ref: "#/definitions/Actor" + - properties: + displayName: + type: string + User: + properties: + id: + type: number + username: + type: string + email: + type: string + displayNSFW: + type: boolean + autoPlayVideo: + type: boolean + role: + type: string + enum: [User, Moderator, Administrator] + videoQuota: + type: number + createdAt: + type: string + account: + $ref: "#/definitions/Account" + videoChannels: + type: array + items: + $ref: "#/definitions/VideoChannel" + ServerConfig: + properties: + signup: + type: object + properties: + allowed: + type: boolean + transcoding: + type: object + properties: + enabledResolutions: + type: array + items: + type: number + avatar: + type: object + properties: + file: + type: object + properties: + size: + type: object + properties: + max: + type: number + extensions: + type: array + items: + type: string + video: + type: object + properties: + file: + type: object + properties: + extensions: + type: array + items: + type: string + Follow: + properties: + id: + type: number + follower: + $ref: "#/definitions/Actor" + following: + $ref: "#/definitions/Actor" + score: + type: number + state: + type: string + enum: [pending, accepted] + createdAt: + type: string + updatedAt: + type: string + Job: + properties: + id: + type: number + state: + type: string + enum: [pending, processing, error, success] + category: + type: string + enum: [transcoding, activitypub-http] + handlerName: + type: string + handlerInputData: + type: string + createdAt: + type: string + updatedAt: + type: string + +#Api responses + AddUserResponse: + properties: + id: + type: number + uuid: + type: string + VideoUploadResponse: + properties: + id: + type: number + uuid: + type: string + +#input bodies + AddUser: + properties: + username: + type: string + description: 'The user username ' + password: + type: string + description: 'The user password ' + email: + type: string + description: 'The user email ' + videoQuota: + type: string + description: 'The user videoQuota ' + role: + type: string + description: 'The user role ' + required: + - username + - password + - email + - videoQuota + - role + UpdateUser: + properties: + id: + type: string + description: 'The user id ' + email: + type: string + description: 'The updated email of the user ' + videoQuota: + type: string + description: 'The updated videoQuota of the user ' + role: + type: string + description: 'The updated role of the user ' + required: + - id + - email + - videoQuota + - role + UpdateMe: + properties: + password: + type: string + description: 'Your new password ' + email: + type: string + description: 'Your new email ' + displayNSFW: + type: string + description: 'Your new displayNSFW ' + autoPlayVideo: + type: string + description: 'Your new autoPlayVideo ' + required: + - password + - email + - displayNSFW + - autoPlayVideo + GetMeVideoRating: + properties: + id: + type: string + description: 'Id of the video ' + rating: + type: number + description: 'Rating of the video ' + required: + - id + - rating + RegisterUser: + properties: + username: + type: string + description: 'The username of the user ' + password: + type: string + description: 'The password of the user ' + email: + type: string + description: 'The email of the user ' + required: + - username + - password + - email + VideoChannelInput: + properties: + name: + type: string + description: + type: string diff --git a/server/controllers/api/server/follows.ts b/server/controllers/api/server/follows.ts index 40b62d977..506b9668e 100644 --- a/server/controllers/api/server/follows.ts +++ b/server/controllers/api/server/follows.ts @@ -17,7 +17,6 @@ import { ActorModel } from '../../../models/activitypub/actor' import { ActorFollowModel } from '../../../models/activitypub/actor-follow' const serverFollowsRouter = express.Router() - serverFollowsRouter.get('/following', paginationValidator, followingSortValidator, -- cgit v1.2.3