Coinduit API Spec

spec.yaml

openapi: 3.0.0
info:
  description: Conduit API
  version: 1.0.0
  title: Conduit API
  contact:
    name: RealWorld
    url: https://realworld.io
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
paths:
  /api/users/login:
    post:
      summary: Existing user login
      description: Login for existing user
      tags:
        - User and Authentication
      operationId: Login
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginUserRequest"
        description: Credentials to use
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  /api/users:
    post:
      summary: Register a new user
      description: Register a new user
      tags:
        - User and Authentication
      operationId: CreateUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewUserRequest"
        description: Details of the new user to register
        required: true
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    get:
      summary: Get current user
      description: Gets the currently logged-in user
      tags:
        - User and Authentication
      security:
        - Token: []
      operationId: GetCurrentUser
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    put:
      summary: Update current user
      description: Updated user information for current user
      tags:
        - User and Authentication
      security:
        - Token: []
      operationId: UpdateCurrentUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
        description: User details to update. At least **one** field is required.
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  "/api/profiles/{username}":
    get:
      summary: Get a profile
      description: Get a profile of a user of the system. Auth is optional
      tags:
        - Profile
      operationId: GetProfileByUsername
      parameters:
        - name: username
          in: path
          description: Username of the profile to get
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfileResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  "/api/profiles/{username}/follow":
    post:
      summary: Follow a user
      description: Follow a user by username
      tags:
        - Profile
      security:
        - Token: []
      operationId: FollowUserByUsername
      parameters:
        - name: username
          in: path
          description: Username of the profile you want to follow
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfileResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    delete:
      summary: Unfollow a user
      description: Unfollow a user by username
      tags:
        - Profile
      security:
        - Token: []
      operationId: UnfollowUserByUsername
      parameters:
        - name: username
          in: path
          description: Username of the profile you want to unfollow
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfileResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  /api/articles/feed:
    get:
      summary: Get recent articles from users you follow
      description: Get most recent articles from users you follow. Use query parameters to
        limit. Auth is required
      tags:
        - Articles
      security:
        - Token: []
      operationId: GetArticlesFeed
      parameters:
        - name: limit
          in: query
          description: Limit number of articles returned (default is 20)
          required: false
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          description: Offset/skip number of articles (default is 0)
          required: false
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipleArticlesResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  /api/articles:
    get:
      summary: Get recent articles globally
      description: Get most recent articles globally. Use query parameters to filter
        results. Auth is optional
      tags:
        - Articles
      operationId: GetArticles
      parameters:
        - name: tag
          in: query
          description: Filter by tag
          required: false
          schema:
            type: string
        - name: author
          in: query
          description: Filter by author (username)
          required: false
          schema:
            type: string
        - name: favorited
          in: query
          description: Filter by favorites of a user (username)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Limit number of articles returned (default is 20)
          required: false
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          description: Offset/skip number of articles (default is 0)
          required: false
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipleArticlesResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    post:
      summary: Create an article
      description: Create an article. Auth is required
      tags:
        - Articles
      security:
        - Token: []
      operationId: CreateArticle
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewArticleRequest"
        description: Article to create
        required: true
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleArticleResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  "/api/articles/{slug}":
    get:
      summary: Get an article
      description: Get an article. Auth not required
      tags:
        - Articles
      operationId: GetArticle
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article to get
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleArticleResponse"
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    put:
      summary: Update an article
      description: Update an article. Auth is required
      tags:
        - Articles
      security:
        - Token: []
      operationId: UpdateArticle
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article to update
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateArticleRequest"
        description: Article to update
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleArticleResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    delete:
      summary: Delete an article
      description: Delete an article. Auth is required
      tags:
        - Articles
      security:
        - Token: []
      operationId: DeleteArticle
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article to delete
          schema:
            type: string
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  "/api/articles/{slug}/comments":
    get:
      summary: Get comments for an article
      description: Get the comments for an article. Auth is optional
      tags:
        - Comments
      operationId: GetArticleComments
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article that you want to get comments for
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultipleCommentsResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    post:
      summary: Create a comment for an article
      description: Create a comment for an article. Auth is required
      tags:
        - Comments
      security:
        - Token: []
      operationId: CreateArticleComment
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article that you want to create a comment for
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCommentRequest"
        description: Comment you want to create
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleCommentResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  "/api/articles/{slug}/comments/{id}":
    delete:
      summary: Delete a comment for an article
      description: Delete a comment for an article. Auth is required
      tags:
        - Comments
      security:
        - Token: []
      operationId: DeleteArticleComment
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article that you want to delete a comment for
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: ID of the comment you want to delete
          schema:
            type: integer
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  "/api/articles/{slug}/favorite":
    post:
      summary: Favorite an article
      description: Favorite an article. Auth is required
      tags:
        - Favorites
      security:
        - Token: []
      operationId: CreateArticleFavorite
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article that you want to favorite
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleArticleResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
    delete:
      summary: Unfavorite an article
      description: Unfavorite an article. Auth is required
      tags:
        - Favorites
      security:
        - Token: []
      operationId: DeleteArticleFavorite
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug of the article that you want to unfavorite
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleArticleResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
  /api/tags:
    get:
      summary: Get tags
      description: Get tags. Auth not required
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagsResponse"
        "422":
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericErrorModel"
servers:
  - url: /api
components:
  securitySchemes:
    Token:
      description: >+
        For accessing the protected API resources, you must have received a a
        valid JWT token after registering or logging in. This JWT token must
        then be used for all protected resources by passing it in via the
        'Authorization' header.


        A JWT token is generated by the API by either registering via /users or logging in via /users/login.


        The following format must be in the 'Authorization' header :

            Token: xxxxxx.yyyyyyy.zzzzzz
            
      type: apiKey
      name: Authorization
      in: header
  schemas:
    LoginUser:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
          format: password
      required:
        - email
        - password
    LoginUserRequest:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/LoginUser"
      required:
        - user
    NewUser:
      type: object
      properties:
        username:
          type: string
        email:
          type: string
        password:
          type: string
          format: password
      required:
        - username
        - email
        - password
    NewUserRequest:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/NewUser"
      required:
        - user
    User:
      type: object
      properties:
        email:
          type: string
        token:
          type: string
        username:
          type: string
        bio:
          type: string
        image:
          type: string
      required:
        - email
        - token
        - username
        - bio
        - image
    UserResponse:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/User"
      required:
        - user
    UpdateUser:
      type: object
      properties:
        email:
          type: string
        token:
          type: string
        username:
          type: string
        bio:
          type: string
        image:
          type: string
    UpdateUserRequest:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/UpdateUser"
      required:
        - user
    ProfileResponse:
      type: object
      properties:
        profile:
          $ref: "#/components/schemas/Profile"
      required:
        - profile
    Profile:
      type: object
      properties:
        username:
          type: string
        bio:
          type: string
        image:
          type: string
        following:
          type: boolean
      required:
        - username
        - bio
        - image
        - following
    Article:
      type: object
      properties:
        slug:
          type: string
        title:
          type: string
        description:
          type: string
        body:
          type: string
        tagList:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        favorited:
          type: boolean
        favoritesCount:
          type: integer
        author:
          $ref: "#/components/schemas/Profile"
      required:
        - slug
        - title
        - description
        - body
        - tagList
        - createdAt
        - updatedAt
        - favorited
        - favoritesCount
        - author
    SingleArticleResponse:
      type: object
      properties:
        article:
          $ref: "#/components/schemas/Article"
      required:
        - article
    MultipleArticlesResponse:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: "#/components/schemas/Article"
        articlesCount:
          type: integer
      required:
        - articles
        - articlesCount
    NewArticle:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        body:
          type: string
        tagList:
          type: array
          items:
            type: string
      required:
        - title
        - description
        - body
    NewArticleRequest:
      type: object
      properties:
        article:
          $ref: "#/components/schemas/NewArticle"
      required:
        - article
    UpdateArticle:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        body:
          type: string
    UpdateArticleRequest:
      type: object
      properties:
        article:
          $ref: "#/components/schemas/UpdateArticle"
      required:
        - article
    Comment:
      type: object
      properties:
        id:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        body:
          type: string
        author:
          $ref: "#/components/schemas/Profile"
      required:
        - id
        - createdAt
        - updatedAt
        - body
        - author
    SingleCommentResponse:
      type: object
      properties:
        comment:
          $ref: "#/components/schemas/Comment"
      required:
        - comment
    MultipleCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: "#/components/schemas/Comment"
      required:
        - comments
    NewComment:
      type: object
      properties:
        body:
          type: string
      required:
        - body
    NewCommentRequest:
      type: object
      properties:
        comment:
          $ref: "#/components/schemas/NewComment"
      required:
        - comment
    TagsResponse:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
      required:
        - tags
    GenericErrorModel:
      type: object
      properties:
        errors:
          type: object
          properties:
            body:
              type: array
              items:
                type: string
          required:
            - body
      required:
        - errors