Commit 01bb93ea authored by Grant's avatar Grant
Browse files

add autogen openapi.yaml

parent 629b6e5d
Loading
Loading
Loading
Loading
Loading

openapi/openapi.yaml

0 → 100644
+280 −0
Original line number Diff line number Diff line
# AUTOGENERATED FILE
# Run bunx bundle:api-doc
openapi: 3.1.1
info:
  title: Fediverse Events API
  version: '1.0'
servers:
  - url: https://api.fediverse.events/v1
    description: Production
security: []
tags:
  - name: events
    x-displayName: Events
    description: Get event related data
  - name: auth
    x-displayName: Authentication
    description: |
      Automated authenciation negotiation for clients
paths:
  /auth:
    get:
      operationId: get-auth
      summary: Get authentication details
      tags:
        - auth
      description: |
        Get the details for automatic authentication on third-party clients

        1. Fetch this endpoint (res)
        2. Send a direct message to `res.account` containing the content of `res.message_template` (replacing the placeholder(s))
        3. Wait for a direct message originating from `res.account` and open the link that gets sent (the message won't contain just the link, the message may contain other text)
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: object
                required:
                  - method
                  - account
                  - message_template
                properties:
                  method:
                    type: string
                    enum:
                      - dm
                  account:
                    type: string
                    example: grant@toast.ooo
                    description: The account handle the message will be sent to
                  message_template:
                    type: string
                    example: |
                      I am requesting a login code
                      EXAMPLE-CODE
                      Sent by {software}
                    description: |
                      The message that should be sent to the account
                      * `{software}` should be replaced with your software's name
        '404':
          x-summary: Not available
          description: Automated authentication is not supported
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
  /events:
    get:
      operationId: get-all-events
      summary: Get all events
      tags:
        - events
      parameters:
        - in: query
          name: from
          schema:
            type: string
            format: date
            default: today
          description: |
            Only include events whose end date is after this date (ISO-8601)
        - in: query
          name: to
          schema:
            type: string
            format: date
            default: today + 1 month
          description: |
            Only include events whose end date is before this date (ISO-8601)
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: object
                required:
                  - events
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_date_iso:
                  summary: '[INVALID_DATE] ISO-8601 format'
                  value:
                    error: INVALID_DATE
                    error_message: Date is not in ISO-8601 format
                invalid_date_order_from:
                  summary: '[INVALID_DATE] from is after to'
                  value:
                    error: INVALID_DATE
                    error_message: '`from` is after `to`'
                invalid_date_order_to:
                  summary: '[INVALID_DATE] to is before from'
                  value:
                    error: INVALID_DATE
                    error_message: '`to` is before `from`'
  /events/{id}:
    parameters:
      - name: id
        in: path
        description: Event ID
        schema:
          type: string
    get:
      operationId: get-event-by-id
      summary: Get event by ID
      tags:
        - events
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          description: Event not found
components:
  schemas:
    URLWithMime:
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          description: Mime type
        url:
          type: string
          format: url
    EventEndpoints:
      type: object
      properties:
        open:
          type: string
          format: url
          description: URL to open the event
        more_info:
          type: string
          format: url
          description: URL for more information
    EventSocial:
      type: array
      items:
        type: object
        required:
          - label
          - icon
          - url
        properties:
          label:
            type: string
          icon:
            type: string
            default: other
            enum:
              - other
              - mastodon
              - lemmy
              - matrix
              - discord
          url:
            type: string
    Event:
      type: object
      x-tags:
        - events
      required:
        - id
        - name
        - start
        - logos
        - endpoints
        - social
      properties:
        id:
          type: string
        name:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        logos:
          type: array
          description: Logos sorted by priority
          items:
            $ref: '#/components/schemas/URLWithMime'
        endpoints:
          $ref: '#/components/schemas/EventEndpoints'
        social:
          $ref: '#/components/schemas/EventSocial'
      examples:
        - id: 123CANVAS001
          name: Canvas 2024
          start: '2024-07-12T04:00:00.000Z'
          end: '2024-07-16T04:00:00.000Z'
          logos:
            - type: image/png
              url: https://example.url
          endpoints:
            open: https://canvas.fediverse.events
            more_info: https://fediverse.events/canvas
          social:
            - label: Community
              icon: lemmy
              url: https://toast.ooo/c/canvas
            - label: Announcements
              icon: mastodon
              url: https://social.fediverse.events/@canvas
            - label: Matrix Space
              icon: matrix
              url: https://matrix.to/#/#canvas:aftermath.gg?via=matrix.org
            - label: Discord
              icon: discord
              url: https://discord.gg/mEUqXZw8kR
        - id: 123CANVAS000
          name: Canvas 2023
          start: '2023-08-04T16:00:00.000Z'
          end: '2023-08-07T03:59:00.000Z'
          logos:
            - type: image/png
              url: https://example.url
          endpoints:
            open: https://canvas.toast.ooo
            more_info: https://toast.ooo/c/canvas
          social:
            - label: Community
              icon: lemmy
              url: https://toast.ooo/c/canvas
    Error:
      type: object
      required:
        - error
        - error_message
      properties:
        error:
          type: string
          description: Error code
        error_message:
          type: string
          description: Human readable error message
+1 −0
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@
  },
  "scripts": {
    "dev": "bun run --hot src/index.ts",
    "bundle:api-doc": "redocly bundle openapi/spec.yml -o openapi/openapi.yaml && sed -i '1s/^/# AUTOGENERATED FILE\\n# Run bunx bundle:api-doc\\n/' openapi/openapi.yaml",
    "build:api-doc": "redocly build-docs openapi/spec.yml -o public/index.html --title \"Fediverse Events API\"",
    "dev:api-doc": "redocly preview-docs openapi/spec.yml",
    "dev:api-ts": "openapi-typescript openapi/spec.yml -o src/types/openapi.d.ts"