goshort/docs/swagger.yml

openapi: "3.0.2"
info:
  version: 1.0.0
  title: GoShort API
  description: Interact with shorts directly via the API.
  license:
    name: AGPL 3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
servers:
  - url: /api
    description: The API server
tags:
  - name: User
    description: Current user
  - name: Shorts
    description: Short management
  - name: Short Logs
    description: Short access logs
x-tagGroups:
  - name: User
    tags:
      - User
  - name: Shorts
    tags:
      - Shorts
      - Short Logs
paths:
  /me:
    get:
      summary: Get user
      description: Returns the current user's info
      operationId: me
      tags:
        - User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/InternalServerError"

  /shorts:
    get:
      summary: List shorts
      description: Lists all shorts belonging to the current user
      operationId: listShorts
      security:
        - Token: []
      tags:
        - Shorts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Short"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/InternalServerError"
    post:
      summary: Create short
      description: Creates a new short for the current user
      operationId: createShort
      tags:
        - Shorts
      requestBody:
        description: Short to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewShort"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Short"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/InternalServerError"

  /shorts/{id}:
    get:
      summary: Find short
      description: Returns a single short by its ID
      operationId: getShort
      tags:
        - Shorts
      parameters:
        - name: id
          in: path
          description: ID of the short to get
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Short"
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/InternalServerError"
    delete:
      summary: Delete short
      description: Deletes a short by its ID
      operationId: deleteShort
      tags:
        - Shorts
      parameters:
        - name: id
          in: path
          description: ID of the short to delete
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/InternalServerError"

  /shorts/{id}/logs:
    get:
      summary: List short views
      description: Lists all views of a short
      operationId: listShortLogs
      tags:
        - Short Logs
      parameters:
        - name: id
          in: path
          description: ID of the short to get logs for
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ShortLog"
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          $ref: "#/components/responses/InternalServerError"
security:
  - Token: []
components:
  schemas:
    User:
      type: object
      required:
        - id
        - username
        - createdAt
      properties:
        id:
          type: string
          example: abc123
        username:
          type: string
          format: email
          example: user@example.com
        createdAt:
          type: string
          format: date-time
          example: 2020-01-01T00:00:00Z
    Short:
      type: object
      allOf:
        - $ref: "#/components/schemas/NewShort"
        - required:
            - id
            - url
            - name
            - shorturl
            - createdAt
          properties:
            id:
              description: ID of the short
              type: string
              example: abc123
            shorturl:
              description: Short URL
              type: string
              format: url
              example: https://goshort.com/my-short-url
            createdAt:
              description: Creation date
              type: string
              format: date-time
              example: 2020-01-01T00:00:00Z
    NewShort:
      type: object
      required:
        - url
      properties:
        url:
          description: URL the short redirects to
          type: string
          format: url
          example: https://my.example.com/very/long/url
        name:
          description: Name of the short, defines the short URL
          type: string
          example: my-short-url
    ShortLog:
      type: object
      required:
        - id
        - shortID
        - ipAddress
        - userAgent
        - referer
        - createdAt
      properties:
        id:
          type: string
          description: ID of the access log
          example: abc123
        shortID:
          type: string
          description: ID of the short
          example: abc123
        ipAddress:
          type: string
          description: IP address of the client
          format: ip
          example: 1.1.1.1
        userAgent:
          type: string
          description: User agent of the client
          example: Mozilla/5.0 (X11; Linux x86_64; rv:72.0) Gecko/20100101 Firefox/72.0
        referer:
          type: string
          description: Referer of the client
          format: url
          example: https://my.referer.com
        createdAt:
          type: string
          format: date-time
          description: Creation date
          example: 2020-01-01T00:00:00Z
    Error:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
        error:
          type: string
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        text/plain:
          schema:
            type: string
    Unauthorized:
      description: Your credentials were missing or incorrect
      content:
        text/plain:
          schema:
            type: string
    Forbidden:
      description: You do not have permission to access this resource
      content:
        text/plain:
          schema:
            type: string
    BadRequest:
      description: Your request was not understood by the server
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalServerError:
      description: An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes:
    Token:
      type: http
      scheme: bearer
      description: |
        The token to authenticate with. It must be sent in the Authorization header as a Bearer token.

        Example:

        `Authorization: Bearer <your-token>`