realworld.json

{
    "openapi": "3.0.1",
    "info": {
        "title": "Conduit API",
        "description": "Conduit API documentation",
        "contact": {
            "name": "RealWorld",
            "url": "https://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": "/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"
            }
        }
    }
}