swagger.yaml

swagger: '2.0'
info:
  title: Blog API
  description: API Documentation for a Blog API
  termsOfService: https://github.com/okeneo/BlogAPI/blob/main/LICENSE
  contact:
    name: okenetega@gmail.com
  license:
    name: MIT License
  version: v1
host: localhost:8000
schemes:
- http
basePath: /api
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Basic:
    type: basic
security:
- Basic: []
paths:
  /categories/:
    get:
      operationId: categories_list
      description: Get all categories.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/Category'
      tags:
      - category
    post:
      operationId: categories_create
      summary: Create a new Category.
      description: The user must be authenticated and must be an admin.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/Category'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/Category'
        '400':
          description: Bad Request
      tags:
      - category
    parameters: []
  /categories/{id}/:
    get:
      operationId: categories_read
      description: Get a category.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - category
    put:
      operationId: categories_update
      summary: Update a category.
      description: The user must be authenticated and must be an admin.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - category
    delete:
      operationId: categories_delete
      summary: Delete a category.
      description: The user must be authenticated and must be an admin.
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - category
    parameters:
    - name: id
      in: path
      required: true
      type: string
  /posts/:
    get:
      operationId: posts_list
      description: Get all posts.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/PostDetail'
      tags:
      - post
    post:
      operationId: posts_create
      summary: Create a new post.
      description: The user must be authenticated and be an author.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PostWrite'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/PostWrite'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized Request
      tags:
      - post
    parameters: []
  /posts/{id}/:
    get:
      operationId: posts_read
      description: Get a specific post.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - post
    put:
      operationId: posts_update
      summary: Update a post.
      description: The user must be authenticated and must be an admin or the author
        of the post.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - post
    delete:
      operationId: posts_delete
      summary: Delete a post.
      description: The user must be authenticated and must be an admin or the author
        of the post.
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - post
    parameters:
    - name: id
      in: path
      required: true
      type: string
  /posts/{id}/comments/:
    get:
      operationId: posts_comments_list
      description: Get all comments under a post.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/CommentTree'
      tags:
      - comment
    post:
      operationId: posts_comments_create
      summary: Create a new comment under a post.
      description: The user must be authenticated.
      parameters: []
      responses:
        '201':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/CommentTree'
      tags:
      - comment
    parameters:
    - name: id
      in: path
      required: true
      type: string
  /posts/{id}/publish/:
    post:
      operationId: posts_publish_create
      summary: Publish an existing post.
      description: The user must be authenticated and must be an admin or the author
        of the post.
      parameters: []
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
        '401':
          description: Unauthorized Request
        '404':
          description: Post Not Found
      tags:
      - post
    parameters:
    - name: id
      in: path
      required: true
      type: string
  /tags/:
    get:
      operationId: tags_list
      description: Get all tags.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/Tag'
      tags:
      - tag
    post:
      operationId: tags_create
      summary: Create a new tag.
      description: The user must be authenticated and must be an admin.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/Tag'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/Tag'
        '400':
          description: Bad Request
      tags:
      - tag
    parameters: []
  /tags/{id}/:
    get:
      operationId: tags_read
      description: Get a tag.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - tag
    put:
      operationId: tags_update
      summary: Update a tag.
      description: The user must be authenticated and must be an admin.
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - tag
    delete:
      operationId: tags_delete
      summary: Delete a tag.
      description: The user must be authenticated and must be an admin.
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - tag
    parameters:
    - name: id
      in: path
      required: true
      type: string
  /token/:
    post:
      operationId: token_create
      description: |-
        Takes a set of user credentials and returns an access and refresh JSON web
        token pair to prove the authentication of those credentials.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/TokenObtainPair'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/TokenObtainPair'
      tags:
      - token
    parameters: []
  /token/blacklist/:
    post:
      operationId: token_blacklist_create
      description: |-
        Takes a token and blacklists it. Must be used with the
        `rest_framework_simplejwt.token_blacklist` app installed.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/TokenBlacklist'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/TokenBlacklist'
      tags:
      - token
    parameters: []
  /token/refresh/:
    post:
      operationId: token_refresh_create
      description: |-
        Takes a refresh type JSON web token and returns an access type JSON web
        token if the refresh token is valid.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/TokenRefresh'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/TokenRefresh'
      tags:
      - token
    parameters: []
  /users/register/:
    post:
      operationId: users_register_create
      description: Create a new user.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          required:
          - username
          - password1
          - password2
          type: object
          properties:
            username:
              type: string
            password1:
              type: string
            password2:
              type: string
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
      tags:
      - user
    parameters: []
  /users/{username}/:
    get:
      operationId: users_read
      summary: Get a user's data.
      description: |-
        Authenticated users will see more data, with the caveat that they need to be an
        admin or the owner of the account.
      parameters:
      - name: username
        in: path
        description: Username
        type: string
        required: true
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/Profile'
        '400':
          description: Bad Request
        '404':
          description: User Not Found
      tags:
      - user
    put:
      operationId: users_update
      summary: Update a user's information.
      description: The user must be authenticated and must be an admin or the owner
        of the account.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/User'
      - name: username
        in: path
        description: Username
        type: string
        required: true
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/User'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized Request
        '404':
          description: User Not Found
      tags:
      - user
    delete:
      operationId: users_delete
      summary: Delete a user.
      description: The user must be authenticated and must be an admin or the owner
        of the account.
      parameters:
      - name: username
        in: path
        description: Username
        type: string
        required: true
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
        '401':
          description: Unauthorized Request
        '404':
          description: User Not Found
      tags:
      - user
    parameters:
    - name: username
      in: path
      required: true
      type: string
definitions:
  Category:
    required:
    - name
    type: object
    properties:
      id:
        title: ID
        type: integer
        readOnly: true
      name:
        title: Name
        type: string
        maxLength: 20
        minLength: 1
  Profile:
    required:
    - bio
    type: object
    properties:
      username:
        title: Username
        type: string
        readOnly: true
      role:
        title: Role
        type: string
        readOnly: true
        maxLength: 10
        minLength: 1
      bio:
        title: Bio
        type: string
        maxLength: 500
  Tag:
    required:
    - name
    type: object
    properties:
      id:
        title: ID
        type: integer
        readOnly: true
      name:
        title: Name
        type: string
        maxLength: 20
        minLength: 1
  PostDetail:
    required:
    - author
    - category
    - tags
    - title
    - body
    type: object
    properties:
      id:
        title: ID
        type: integer
        readOnly: true
      author:
        $ref: '#/definitions/Profile'
      category:
        $ref: '#/definitions/Category'
      tags:
        type: array
        items:
          $ref: '#/definitions/Tag'
      title:
        title: Title
        type: string
        maxLength: 255
        minLength: 1
      subtitle:
        title: Subtitle
        type: string
        maxLength: 255
      body:
        title: Body
        type: string
        minLength: 1
      date_created:
        title: Date created
        type: string
        format: date-time
        readOnly: true
      date_modified:
        title: Date modified
        type: string
        format: date-time
        readOnly: true
      publish_date:
        title: Publish date
        type: string
        format: date-time
        x-nullable: true
      published:
        title: Published
        type: boolean
  PostWrite:
    required:
    - title
    - body
    - author
    - category
    type: object
    properties:
      id:
        title: ID
        type: integer
        readOnly: true
      title:
        title: Title
        type: string
        maxLength: 255
        minLength: 1
      subtitle:
        title: Subtitle
        type: string
        maxLength: 255
      body:
        title: Body
        type: string
        minLength: 1
      author:
        title: Author
        type: integer
      category:
        title: Category
        type: integer
      tags:
        type: array
        items:
          type: integer
        uniqueItems: true
  CommentTree:
    required:
    - text
    - user
    - post
    type: object
    properties:
      id:
        title: ID
        type: integer
        readOnly: true
      replies:
        title: Replies
        type: string
        readOnly: true
      text:
        title: Text
        type: string
        minLength: 1
      date_created:
        title: Date created
        type: string
        format: date-time
        readOnly: true
      date_modified:
        title: Date modified
        type: string
        format: date-time
        readOnly: true
      user:
        title: User
        type: integer
      post:
        title: Post
        type: integer
      parent_comment:
        title: Parent comment
        type: integer
        x-nullable: true
  TokenObtainPair:
    required:
    - username
    - password
    type: object
    properties:
      username:
        title: Username
        type: string
        minLength: 1
      password:
        title: Password
        type: string
        minLength: 1
  TokenBlacklist:
    required:
    - refresh
    type: object
    properties:
      refresh:
        title: Refresh
        type: string
        minLength: 1
  TokenRefresh:
    required:
    - refresh
    type: object
    properties:
      refresh:
        title: Refresh
        type: string
        minLength: 1
      access:
        title: Access
        type: string
        readOnly: true
        minLength: 1
  User:
    required:
    - username
    - email
    - first_name
    - last_name
    - password1
    - password2
    - profile
    type: object
    properties:
      username:
        title: Username
        type: string
        maxLength: 150
        minLength: 1
      email:
        title: Email
        type: string
        format: email
      first_name:
        title: First name
        type: string
        maxLength: 150
      last_name:
        title: Last name
        type: string
        maxLength: 150
      password1:
        title: Password1
        type: string
        minLength: 1
      password2:
        title: Password2
        type: string
        minLength: 1
      profile:
        $ref: '#/definitions/Profile'