api/api.yaml

openapi: 3.0.3
info:
  title: TheAdversary api
  description: TheAdversary api
  version: 1.0.0
servers:
  - url: 'http://localhost:8080'
paths:
  /api/login:
    post:
      summary: Login to an author account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Username of the user / author which logs in
                password:
                  type: string
                  description: Password of the user
      responses:
        200:
          description: Logged in
          headers:
            Set-Cookie:
              schema:
                type: string
                description: The session_id cookie to authenticate
        401:
          description: Login failed

  /api/authors:
    get:
      summary: Get authors
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Name (or a part of it) to filter tags after it
        - in: query
          name: limit
          schema:
            type: integer
          description: Limit of recent authors to return
      responses:
        200:
          description: All found authors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Author'
                description: Array of all found authors

  /api/tags:
    get:
      summary: Get tags
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Name (or a part of it) to filter tags after it
        - in: query
          name: limit
          schema:
            type: integer
          description: Limit of recent tags to return
      responses:
        200:
          description: All found tags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
                description: Array of all found tags

  /api/recent:
    get:
      summary: Get recent articles
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
          description: Limit of recent articles to return
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  articles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArticleSummary'
                      
  /api/search:
    get:
      summary: Search all articles
      parameters:
        - in: query
          name: q
          schema:
            type: string
          description: Name of the article to search
        - in: query
          name: from
          schema:
            type: string
          description: A RFC3339 formatted date to start searching when articles are older than specified
        - in: query
          name: to
          schema:
            type: string
          description: A RFC3339 formatted date to stop searching when articles are older than specified
        - in: query
          name: limit
          schema:
            type: integer
          description: Limit of articles to return
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  articles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArticleSummary'

  /api/upload:
    post:
      summary: "Uploads a new article"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: "Name of the article. Must be unique"
                summary:
                  type: string
                  description: A short overview summary of the article
                image:
                  type: string
                  description: Link to a preview image
                  nullable: true
                tags:
                  type: array
                  description: Tags the article should have. If the tag does not exist, a new one is created automatically
                  items:
                    $ref: '#/components/schemas/Tag'
                content:
                  type: string
                  description: The article itself, formatted as markdown
      security:
        - cookie: []
      
      responses:
        201:
          description: The article was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleSummary'
        401:
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        409:
          description: A article with the same title already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
                
components:
  schemas:
    ApiError:
      type: object
      properties:
        message:
          type: string
          description: Error message
    ArticleSummary:
      type: object
      properties:
        id:
          type: number
          description: The article id
        title:
          type: string
          description: Title of the article
        summary:
          type: string
          description: A short overview summary of the article
        author:
          $ref: '#/components/schemas/Author'
        image:
          type: string
          description: Link to a preview image
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        link:
          type: string
          description: Link to the article itself
    Author:
      type: object
      properties:
        id:
          type: number
          description: Id of the author
        name:
          type: string
          description: The author name
        information:
          type: string
          description: Further information about the author
          nullable: true
    Tag:
      type: object
      properties:
        id:
          type: number
          description: The tag id
        name:
          type: string
          description: Name of the tag
  securitySchemes:
    cookie:
      type: apiKey
      in: cookie
      name: session_id