swagger.json

{
  "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"
            }
          }
        }
      }
    },
    "/user": {
      "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"
      ]
    }
  }
}