realworld.yaml

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