{
  "openapi": "3.0.1",
  "info": {
    "title": "RealWorld Conduit API",
    "description": "Conduit API documentation",
    "contact": {
      "name": "RealWorld",
      "url": "https://www.realworld.how"
    },
    "license": {
      "name": "MIT License",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "Articles"
    },
    {
      "name": "Comments"
    },
    {
      "name": "Favorites"
    },
    {
      "name": "Profile"
    },
    {
      "name": "Tags"
    },
    {
      "name": "User and Authentication"
    }
  ],
  "servers": [
    {
      "url": "https://api.realworld.io/api"
    }
  ],
  "paths": {
    "/users/login": {
      "post": {
        "tags": [
          "User and Authentication"
        ],
        "summary": "Existing user login",
        "description": "Login for existing user",
        "operationId": "Login",
        "requestBody": {
          "$ref": "#/components/requestBodies/LoginUserRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/UserResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "x-codegen-request-body-name": "body"
      }
    },
    "/users": {
      "post": {
        "tags": [
          "User and Authentication"
        ],
        "description": "Register a new user",
        "operationId": "CreateUser",
        "requestBody": {
          "$ref": "#/components/requestBodies/NewUserRequest"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/UserResponse"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "x-codegen-request-body-name": "body"
      }
    },
    "/user": {
      "get": {
        "tags": [
          "User and Authentication"
        ],
        "summary": "Get current user",
        "description": "Gets the currently logged-in user",
        "operationId": "GetCurrentUser",
        "responses": {
          "200": {
            "$ref": "#/components/responses/UserResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      },
      "put": {
        "tags": [
          "User and Authentication"
        ],
        "summary": "Update current user",
        "description": "Updated user information for current user",
        "operationId": "UpdateCurrentUser",
        "requestBody": {
          "$ref": "#/components/requestBodies/UpdateUserRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/UserResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ],
        "x-codegen-request-body-name": "body"
      }
    },
    "/profiles/{username}": {
      "get": {
        "tags": [
          "Profile"
        ],
        "summary": "Get a profile",
        "description": "Get a profile of a user of the system. Auth is optional",
        "operationId": "GetProfileByUsername",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "description": "Username of the profile to get",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ProfileResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        }
      }
    },
    "/profiles/{username}/follow": {
      "post": {
        "tags": [
          "Profile"
        ],
        "summary": "Follow a user",
        "description": "Follow a user by username",
        "operationId": "FollowUserByUsername",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "description": "Username of the profile you want to follow",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ProfileResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Profile"
        ],
        "summary": "Unfollow a user",
        "description": "Unfollow a user by username",
        "operationId": "UnfollowUserByUsername",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "description": "Username of the profile you want to unfollow",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ProfileResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      }
    },
    "/articles/feed": {
      "get": {
        "tags": [
          "Articles"
        ],
        "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",
        "operationId": "GetArticlesFeed",
        "parameters": [
          {
            "$ref": "#/components/parameters/offsetParam"
          },
          {
            "$ref": "#/components/parameters/limitParam"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/MultipleArticlesResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      }
    },
    "/articles": {
      "get": {
        "tags": [
          "Articles"
        ],
        "summary": "Get recent articles globally",
        "description": "Get most recent articles globally. Use query parameters to filter results. Auth is optional",
        "operationId": "GetArticles",
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "description": "Filter by tag",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "author",
            "in": "query",
            "description": "Filter by author (username)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "favorited",
            "in": "query",
            "description": "Filter by favorites of a user (username)",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/offsetParam"
          },
          {
            "$ref": "#/components/parameters/limitParam"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/MultipleArticlesResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        }
      },
      "post": {
        "tags": [
          "Articles"
        ],
        "summary": "Create an article",
        "description": "Create an article. Auth is required",
        "operationId": "CreateArticle",
        "requestBody": {
          "$ref": "#/components/requestBodies/NewArticleRequest"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/SingleArticleResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ],
        "x-codegen-request-body-name": "article"
      }
    },
    "/articles/{slug}": {
      "get": {
        "tags": [
          "Articles"
        ],
        "summary": "Get an article",
        "description": "Get an article. Auth not required",
        "operationId": "GetArticle",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article to get",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SingleArticleResponse"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        }
      },
      "put": {
        "tags": [
          "Articles"
        ],
        "summary": "Update an article",
        "description": "Update an article. Auth is required",
        "operationId": "UpdateArticle",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article to update",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/UpdateArticleRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SingleArticleResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ],
        "x-codegen-request-body-name": "article"
      },
      "delete": {
        "tags": [
          "Articles"
        ],
        "summary": "Delete an article",
        "description": "Delete an article. Auth is required",
        "operationId": "DeleteArticle",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article to delete",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/EmptyOkResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      }
    },
    "/articles/{slug}/comments": {
      "get": {
        "tags": [
          "Comments"
        ],
        "summary": "Get comments for an article",
        "description": "Get the comments for an article. Auth is optional",
        "operationId": "GetArticleComments",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article that you want to get comments for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/MultipleCommentsResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        }
      },
      "post": {
        "tags": [
          "Comments"
        ],
        "summary": "Create a comment for an article",
        "description": "Create a comment for an article. Auth is required",
        "operationId": "CreateArticleComment",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article that you want to create a comment for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/NewCommentRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SingleCommentResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ],
        "x-codegen-request-body-name": "comment"
      }
    },
    "/articles/{slug}/comments/{id}": {
      "delete": {
        "tags": [
          "Comments"
        ],
        "summary": "Delete a comment for an article",
        "description": "Delete a comment for an article. Auth is required",
        "operationId": "DeleteArticleComment",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article that you want to delete a comment for",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "ID of the comment you want to delete",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/EmptyOkResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      }
    },
    "/articles/{slug}/favorite": {
      "post": {
        "tags": [
          "Favorites"
        ],
        "summary": "Favorite an article",
        "description": "Favorite an article. Auth is required",
        "operationId": "CreateArticleFavorite",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article that you want to favorite",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SingleArticleResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Favorites"
        ],
        "summary": "Unfavorite an article",
        "description": "Unfavorite an article. Auth is required",
        "operationId": "DeleteArticleFavorite",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Slug of the article that you want to unfavorite",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/SingleArticleResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        },
        "security": [
          {
            "Token": []
          }
        ]
      }
    },
    "/tags": {
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "Get tags",
        "description": "Get tags. Auth not required",
        "operationId": "GetTags",
        "responses": {
          "200": {
            "$ref": "#/components/responses/TagsResponse"
          },
          "422": {
            "$ref": "#/components/responses/GenericError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LoginUser": {
        "required": [
          "email",
          "password"
        ],
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "format": "password"
          }
        }
      },
      "NewUser": {
        "required": [
          "email",
          "password",
          "username"
        ],
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "format": "password"
          }
        }
      },
      "User": {
        "required": [
          "bio",
          "email",
          "image",
          "token",
          "username"
        ],
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "token": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "bio": {
            "type": "string"
          },
          "image": {
            "type": "string"
          }
        }
      },
      "UpdateUser": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "bio": {
            "type": "string"
          },
          "image": {
            "type": "string"
          }
        }
      },
      "Profile": {
        "required": [
          "bio",
          "following",
          "image",
          "username"
        ],
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "bio": {
            "type": "string"
          },
          "image": {
            "type": "string"
          },
          "following": {
            "type": "boolean"
          }
        }
      },
      "Article": {
        "required": [
          "author",
          "body",
          "createdAt",
          "description",
          "favorited",
          "favoritesCount",
          "slug",
          "tagList",
          "title",
          "updatedAt"
        ],
        "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": "#/components/schemas/Profile"
          }
        }
      },
      "NewArticle": {
        "required": [
          "body",
          "description",
          "title"
        ],
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "tagList": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "UpdateArticle": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        }
      },
      "Comment": {
        "required": [
          "author",
          "body",
          "createdAt",
          "id",
          "updatedAt"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "body": {
            "type": "string"
          },
          "author": {
            "$ref": "#/components/schemas/Profile"
          }
        }
      },
      "NewComment": {
        "required": [
          "body"
        ],
        "type": "object",
        "properties": {
          "body": {
            "type": "string"
          }
        }
      },
      "GenericErrorModel": {
        "required": [
          "errors"
        ],
        "type": "object",
        "properties": {
          "errors": {
            "required": [
              "body"
            ],
            "type": "object",
            "properties": {
              "body": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "TagsResponse": {
        "description": "Tags",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "tags"
              ],
              "type": "object",
              "properties": {
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "SingleCommentResponse": {
        "description": "Single comment",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "comment"
              ],
              "type": "object",
              "properties": {
                "comment": {
                  "$ref": "#/components/schemas/Comment"
                }
              }
            }
          }
        }
      },
      "MultipleCommentsResponse": {
        "description": "Multiple comments",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "comments"
              ],
              "type": "object",
              "properties": {
                "comments": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Comment"
                  }
                }
              }
            }
          }
        }
      },
      "SingleArticleResponse": {
        "description": "Single article",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "article"
              ],
              "type": "object",
              "properties": {
                "article": {
                  "$ref": "#/components/schemas/Article"
                }
              }
            }
          }
        }
      },
      "MultipleArticlesResponse": {
        "description": "Multiple articles",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "articles",
                "articlesCount"
              ],
              "type": "object",
              "properties": {
                "articles": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Article"
                  }
                },
                "articlesCount": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "ProfileResponse": {
        "description": "Profile",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "profile"
              ],
              "type": "object",
              "properties": {
                "profile": {
                  "$ref": "#/components/schemas/Profile"
                }
              }
            }
          }
        }
      },
      "UserResponse": {
        "description": "User",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "user"
              ],
              "type": "object",
              "properties": {
                "user": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      },
      "EmptyOkResponse": {
        "description": "No content",
        "content": {}
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {}
      },
      "GenericError": {
        "description": "Unexpected error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/GenericErrorModel"
            }
          }
        }
      }
    },
    "requestBodies": {
      "LoginUserRequest": {
        "required": true,
        "description": "Credentials to use",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "user"
              ],
              "type": "object",
              "properties": {
                "user": {
                  "$ref": "#/components/schemas/LoginUser"
                }
              }
            }
          }
        }
      },
      "NewUserRequest": {
        "required": true,
        "description": "Details of the new user to register",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "user"
              ],
              "type": "object",
              "properties": {
                "user": {
                  "$ref": "#/components/schemas/NewUser"
                }
              }
            }
          }
        }
      },
      "UpdateUserRequest": {
        "required": true,
        "description": "User details to update. At least **one** field is required.",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "user"
              ],
              "type": "object",
              "properties": {
                "user": {
                  "$ref": "#/components/schemas/UpdateUser"
                }
              }
            }
          }
        }
      },
      "NewArticleRequest": {
        "required": true,
        "description": "Article to create",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "article"
              ],
              "type": "object",
              "properties": {
                "article": {
                  "$ref": "#/components/schemas/NewArticle"
                }
              }
            }
          }
        }
      },
      "UpdateArticleRequest": {
        "required": true,
        "description": "Article to update",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "article"
              ],
              "type": "object",
              "properties": {
                "article": {
                  "$ref": "#/components/schemas/UpdateArticle"
                }
              }
            }
          }
        }
      },
      "NewCommentRequest": {
        "required": true,
        "description": "Comment you want to create",
        "content": {
          "application/json": {
            "schema": {
              "required": [
                "comment"
              ],
              "type": "object",
              "properties": {
                "comment": {
                  "$ref": "#/components/schemas/NewComment"
                }
              }
            }
          }
        }
      }
    },
    "parameters": {
      "offsetParam": {
        "in": "query",
        "name": "offset",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0
        },
        "description": "The number of items to skip before starting to collect the result set."
      },
      "limitParam": {
        "in": "query",
        "name": "limit",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 20
        },
        "description": "The numbers of items to return."
      }
    },
    "securitySchemes": {
      "Token": {
        "type": "apiKey",
        "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",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}