{
"swagger": "2.0",
"info": {
"description": "Conduit API",
"version": "1.0.0",
"title": "Conduit API",
"contact": {
"name": "RealWorld",
"url": "https://realworld.io"
},
"license": {
"name": "MIT License",
"url": "https://opensource.org/licenses/MIT"
}
},
"basePath": "/api",
"schemes": [
"https",
"http"
],
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"securityDefinitions": {
"Token": {
"description": "For accessing the protected API resources, you must have received a a valid JWT token after registering or logging in. This JWT token must then be used for all protected resources by passing it in via the 'Authorization' header.\n\nA JWT token is generated by the API by either registering via /users or logging in via /users/login.\n\nThe following format must be in the 'Authorization' header :\n\n Token: xxxxxx.yyyyyyy.zzzzzz\n \n",
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
},
"paths": {
"/users/login": {
"post": {
"summary": "Existing user login",
"description": "Login for existing user",
"tags": [
"User and Authentication"
],
"operationId": "Login",
"parameters": [
{
"name": "body",
"in": "body",
"required": true,
"description": "Credentials to use",
"schema": {
"$ref": "#/definitions/LoginUserRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/UserResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/users": {
"post": {
"summary": "Register a new user",
"description": "Register a new user",
"tags": [
"User and Authentication"
],
"operationId": "CreateUser",
"parameters": [
{
"name": "body",
"in": "body",
"required": true,
"description": "Details of the new user to register",
"schema": {
"$ref": "#/definitions/NewUserRequest"
}
}
],
"responses": {
"201": {
"description": "OK",
"schema": {
"$ref": "#/definitions/UserResponse"
}
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"get": {
"summary": "Get current user",
"description": "Gets the currently logged-in user",
"tags": [
"User and Authentication"
],
"security": [
{
"Token": []
}
],
"operationId": "GetCurrentUser",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/UserResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"put": {
"summary": "Update current user",
"description": "Updated user information for current user",
"tags": [
"User and Authentication"
],
"security": [
{
"Token": []
}
],
"operationId": "UpdateCurrentUser",
"parameters": [
{
"name": "body",
"in": "body",
"required": true,
"description": "User details to update. At least **one** field is required.",
"schema": {
"$ref": "#/definitions/UpdateUserRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/UserResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/profiles/{username}": {
"get": {
"summary": "Get a profile",
"description": "Get a profile of a user of the system. Auth is optional",
"tags": [
"Profile"
],
"operationId": "GetProfileByUsername",
"parameters": [
{
"name": "username",
"in": "path",
"description": "Username of the profile to get",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/ProfileResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/profiles/{username}/follow": {
"post": {
"summary": "Follow a user",
"description": "Follow a user by username",
"tags": [
"Profile"
],
"security": [
{
"Token": []
}
],
"operationId": "FollowUserByUsername",
"parameters": [
{
"name": "username",
"in": "path",
"description": "Username of the profile you want to follow",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/ProfileResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"delete": {
"summary": "Unfollow a user",
"description": "Unfollow a user by username",
"tags": [
"Profile"
],
"security": [
{
"Token": []
}
],
"operationId": "UnfollowUserByUsername",
"parameters": [
{
"name": "username",
"in": "path",
"description": "Username of the profile you want to unfollow",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/ProfileResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/articles/feed": {
"get": {
"summary": "Get recent articles from users you follow",
"description": "Get most recent articles from users you follow. Use query parameters to limit. Auth is required",
"tags": [
"Articles"
],
"security": [
{
"Token": []
}
],
"operationId": "GetArticlesFeed",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Limit number of articles returned (default is 20)",
"required": false,
"default": 20,
"type": "integer"
},
{
"name": "offset",
"in": "query",
"description": "Offset/skip number of articles (default is 0)",
"required": false,
"default": 0,
"type": "integer"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/MultipleArticlesResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/articles": {
"get": {
"summary": "Get recent articles globally",
"description": "Get most recent articles globally. Use query parameters to filter results. Auth is optional",
"tags": [
"Articles"
],
"operationId": "GetArticles",
"parameters": [
{
"name": "tag",
"in": "query",
"description": "Filter by tag",
"required": false,
"type": "string"
},
{
"name": "author",
"in": "query",
"description": "Filter by author (username)",
"required": false,
"type": "string"
},
{
"name": "favorited",
"in": "query",
"description": "Filter by favorites of a user (username)",
"required": false,
"type": "string"
},
{
"name": "limit",
"in": "query",
"description": "Limit number of articles returned (default is 20)",
"required": false,
"default": 20,
"type": "integer"
},
{
"name": "offset",
"in": "query",
"description": "Offset/skip number of articles (default is 0)",
"required": false,
"default": 0,
"type": "integer"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/MultipleArticlesResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"post": {
"summary": "Create an article",
"description": "Create an article. Auth is required",
"tags": [
"Articles"
],
"security": [
{
"Token": []
}
],
"operationId": "CreateArticle",
"parameters": [
{
"name": "article",
"in": "body",
"required": true,
"description": "Article to create",
"schema": {
"$ref": "#/definitions/NewArticleRequest"
}
}
],
"responses": {
"201": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SingleArticleResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/articles/{slug}": {
"get": {
"summary": "Get an article",
"description": "Get an article. Auth not required",
"tags": [
"Articles"
],
"operationId": "GetArticle",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article to get",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SingleArticleResponse"
}
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"put": {
"summary": "Update an article",
"description": "Update an article. Auth is required",
"tags": [
"Articles"
],
"security": [
{
"Token": []
}
],
"operationId": "UpdateArticle",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article to update",
"type": "string"
},
{
"name": "article",
"in": "body",
"required": true,
"description": "Article to update",
"schema": {
"$ref": "#/definitions/UpdateArticleRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SingleArticleResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"delete": {
"summary": "Delete an article",
"description": "Delete an article. Auth is required",
"tags": [
"Articles"
],
"security": [
{
"Token": []
}
],
"operationId": "DeleteArticle",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article to delete",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/articles/{slug}/comments": {
"get": {
"summary": "Get comments for an article",
"description": "Get the comments for an article. Auth is optional",
"tags": [
"Comments"
],
"operationId": "GetArticleComments",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article that you want to get comments for",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/MultipleCommentsResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"post": {
"summary": "Create a comment for an article",
"description": "Create a comment for an article. Auth is required",
"tags": [
"Comments"
],
"security": [
{
"Token": []
}
],
"operationId": "CreateArticleComment",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article that you want to create a comment for",
"type": "string"
},
{
"name": "comment",
"in": "body",
"required": true,
"description": "Comment you want to create",
"schema": {
"$ref": "#/definitions/NewCommentRequest"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SingleCommentResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/articles/{slug}/comments/{id}": {
"delete": {
"summary": "Delete a comment for an article",
"description": "Delete a comment for an article. Auth is required",
"tags": [
"Comments"
],
"security": [
{
"Token": []
}
],
"operationId": "DeleteArticleComment",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article that you want to delete a comment for",
"type": "string"
},
{
"name": "id",
"in": "path",
"required": true,
"description": "ID of the comment you want to delete",
"type": "integer"
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/articles/{slug}/favorite": {
"post": {
"summary": "Favorite an article",
"description": "Favorite an article. Auth is required",
"tags": [
"Favorites"
],
"security": [
{
"Token": []
}
],
"operationId": "CreateArticleFavorite",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article that you want to favorite",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SingleArticleResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
},
"delete": {
"summary": "Unfavorite an article",
"description": "Unfavorite an article. Auth is required",
"tags": [
"Favorites"
],
"security": [
{
"Token": []
}
],
"operationId": "DeleteArticleFavorite",
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "Slug of the article that you want to unfavorite",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/SingleArticleResponse"
}
},
"401": {
"description": "Unauthorized"
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
},
"/tags": {
"get": {
"summary": "Get tags",
"description": "Get tags. Auth not required",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/TagsResponse"
}
},
"422": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/GenericErrorModel"
}
}
}
}
}
},
"definitions": {
"LoginUser": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"password": {
"type": "string",
"format": "password"
}
},
"required": [
"email",
"password"
]
},
"LoginUserRequest": {
"type": "object",
"properties": {
"user": {
"$ref": "#/definitions/LoginUser"
}
},
"required": [
"user"
]
},
"NewUser": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"email": {
"type": "string"
},
"password": {
"type": "string",
"format": "password"
}
},
"required": [
"username",
"email",
"password"
]
},
"NewUserRequest": {
"type": "object",
"properties": {
"user": {
"$ref": "#/definitions/NewUser"
}
},
"required": [
"user"
]
},
"User": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"token": {
"type": "string"
},
"username": {
"type": "string"
},
"bio": {
"type": "string"
},
"image": {
"type": "string"
}
},
"required": [
"email",
"token",
"username",
"bio",
"image"
]
},
"UserResponse": {
"type": "object",
"properties": {
"user": {
"$ref": "#/definitions/User"
}
},
"required": [
"user"
]
},
"UpdateUser": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"token": {
"type": "string"
},
"username": {
"type": "string"
},
"bio": {
"type": "string"
},
"image": {
"type": "string"
}
}
},
"UpdateUserRequest": {
"type": "object",
"properties": {
"user": {
"$ref": "#/definitions/UpdateUser"
}
},
"required": [
"user"
]
},
"ProfileResponse": {
"type": "object",
"properties": {
"profile": {
"$ref": "#/definitions/Profile"
}
},
"required": [
"profile"
]
},
"Profile": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"bio": {
"type": "string"
},
"image": {
"type": "string"
},
"following": {
"type": "boolean"
}
},
"required": [
"username",
"bio",
"image",
"following"
]
},
"Article": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"body": {
"type": "string"
},
"tagList": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"favorited": {
"type": "boolean"
},
"favoritesCount": {
"type": "integer"
},
"author": {
"$ref": "#/definitions/Profile"
}
},
"required": [
"slug",
"title",
"description",
"body",
"tagList",
"createdAt",
"updatedAt",
"favorited",
"favoritesCount",
"author"
]
},
"SingleArticleResponse": {
"type": "object",
"properties": {
"article": {
"$ref": "#/definitions/Article"
}
},
"required": [
"article"
]
},
"MultipleArticlesResponse": {
"type": "object",
"properties": {
"articles": {
"type": "array",
"items": {
"$ref": "#/definitions/Article"
}
},
"articlesCount": {
"type": "integer"
}
},
"required": [
"articles",
"articlesCount"
]
},
"NewArticle": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"body": {
"type": "string"
},
"tagList": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"title",
"description",
"body"
]
},
"NewArticleRequest": {
"type": "object",
"properties": {
"article": {
"$ref": "#/definitions/NewArticle"
}
},
"required": [
"article"
]
},
"UpdateArticle": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"body": {
"type": "string"
}
}
},
"UpdateArticleRequest": {
"type": "object",
"properties": {
"article": {
"$ref": "#/definitions/UpdateArticle"
}
},
"required": [
"article"
]
},
"Comment": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"body": {
"type": "string"
},
"author": {
"$ref": "#/definitions/Profile"
}
},
"required": [
"id",
"createdAt",
"updatedAt",
"body",
"author"
]
},
"SingleCommentResponse": {
"type": "object",
"properties": {
"comment": {
"$ref": "#/definitions/Comment"
}
},
"required": [
"comment"
]
},
"MultipleCommentsResponse": {
"type": "object",
"properties": {
"comments": {
"type": "array",
"items": {
"$ref": "#/definitions/Comment"
}
}
},
"required": [
"comments"
]
},
"NewComment": {
"type": "object",
"properties": {
"body": {
"type": "string"
}
},
"required": [
"body"
]
},
"NewCommentRequest": {
"type": "object",
"properties": {
"comment": {
"$ref": "#/definitions/NewComment"
}
},
"required": [
"comment"
]
},
"TagsResponse": {
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"tags"
]
},
"GenericErrorModel": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"body": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"body"
]
}
},
"required": [
"errors"
]
}
}
}