openapi.yml

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:
                  required:
                    - author
                    - createdAt
                    - description
                    - favorited
                    - favoritesCount
                    - slug
                    - tagList
                    - title
                    - updatedAt
                  type: object
                  properties:
                    slug:
                      type: string
                    title:
                      type: string
                    description:
                      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'
              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