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: number
          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: number
          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: number
          description: Limit of recent articles to return
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                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: Date to start searching when the article was created or modified, given in unix seconds
        - in: query
          name: to
          schema:
            type: string
          description: Date to end searching when the article was created or modified, given in unix seconds
        - in: query
          name: authors
          schema:
            type: array
          description: Ids of authors to limit the search
        - in: query
          name: tags
          schema:
            type: array
          description: Ids of tags to limit the search
        - in: query
          name: limit
          schema:
            type: number
          description: Limit of articles to return
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleSummary'

  /api/article:
    get:
      summary: Get an article by its id
      parameters:
        - in: query
          name: id
          schema:
            type: number
          description: The id of the article
      security:
        - cookie: []
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                    description: The title of the article
                  summary:
                    type: string
                    description: The articles' summary
                  authors:
                    type: array
                    items:
                      type: number
                    description: A array of author ids which have been worked on it
                  image:
                    type: string
                    description: A (optional) preview image
                  tags:
                    type: array
                    items:
                      type: string
                    description: A array of tags which are set to the article
                  link:
                    type: string
                    description: The link name (last path of the url) which redirects to the article
                  content:
                    type: string
                    description: The article itself (its content), encoded as base64
        401:
          description: Not authorized (either no valid cookie or no author from the given article)
        404:
          description: No article with the given id
        422:
          description: Invalid id parameter was given
    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
                authors:
                  type: array
                  items:
                    type: number
                    description: A author id
                  description: List of additional authors as id which contributed to the article. The author which sends this request is automatically added as (main) author
                image:
                  type: string
                  description: Link to a preview image
                  nullable: true
                tags:
                  type: array
                  items:
                    type: string
                    description: A tag name
                  description: Tags the article should have. If the tag does not exist, a new one is created automatically
                link:
                  type: string
                  description: The link name (last path of the url) which redirects to the article
                  nullable: true
                content:
                  type: string
                  description: The article itself, formatted as markdown. Must be encoded as base64
      security:
        - cookie: []
      responses:
        201:
          description: The article was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleSummary'
        401:
          description: Not authorized
        409:
          description: A article with the same title already exists
    patch:
      summary: Edits an already existing article
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: number
                  description: Id of the article to edit
                title:
                  type: string
                  description: "Name of the article. Must be unique"
                  nullable: true
                summary:
                  type: string
                  description: A short overview summary of the article
                  nullable: true
                authors:
                  type: array
                  items:
                    type: number
                    description: A author id
                  description: List of additional authors as id which contributed to the article. The author which sends this request is automatically added as (main) author
                  nullable: true
                image:
                  type: string
                  description: Link to a preview image
                  nullable: true
                tags:
                  type: array
                  items:
                    type: string
                    description: A tag name
                  description: Tags the article should have. If the tag does not exist, a new one is created automatically
                  nullable: true
                link:
                  type: string
                  description: The link name (last path of the url) which redirects to the article
                  nullable: true
                content:
                  type: string
                  description: The article itself, formatted as markdown. Must be encoded as base64
                  nullable: true

      security:
        - cookie: []
      responses:
        200:
          description: The article was edited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleSummary'
        401:
          description: Not authorized
        404:
          description: Article was not found
        409:
          description: A article with the same title already exists
    delete:
      summary: Deletes an article
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: number
                  description: Id of the article to delete
      security:
        - cookie: []
      responses:
        200:
          description: The article was deleted
        401:
          description: Not authorized
        404:
          description: Article was not found

  /api/assets:
    get:
      summary: Get a list of assets
      parameters:
        - in: query
          name: q
          schema:
            type: string
          description: Name of assets to search
        - in: query
          name: limit
          schema:
            type: number
          description: Limit of assets to return
      security:
        - cookie: []
      responses:
        200:
          description: All assets of the article
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
        401:
          description: Not authorized
    post:
      summary: Adds a new asset to an article
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the file
                file:
                  type: string
                  format: binary
                  description: The file itself
      security:
        - cookie: []
      responses:
        201:
          description: The asset was created / uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        401:
          description: Not authorized
        409:
          description: A asset with the same name already exists
    delete:
      summary: Deletes assets
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: number
                  description: Id of the assets to delete
      security:
        - cookie: []
      responses:
        200:
          description: The asset was sucessfully deleted
        401:
          description: Not authorized
        404:
          description: An asset with this id does not exist
                
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
        authors:
          type: array
          items:
            type: number
            description: Id of authors to add
        image:
          type: string
          description: Link to a preview image
          nullable: true
        tags:
          type: array
          items:
            type: number
            description: Id of tags to add
        created:
          type: string
          description: Date when the article was created, given in unix seconds
        modified:
          type: string
          description: Date when the article was last modified, given in unix seconds
          nullable: true
        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
    Asset:
      type: object
      properties:
        id:
          type: number
          description: Id of the asset
        name:
          type: string
          description: Name of the asset
        link:
          type: string
          description: Static link to the asset
  securitySchemes:
    cookie:
      type: apiKey
      in: cookie
      name: session_id