Begin OpenAPI Specification

.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+*.log
+

doc/openapi.yaml

@@ -0,0 +1,247 @@
+openapi: 3.0.0
+info:
+  title: Bible API
+  description: API for accessing and searching biblical information.
+  version: 1.0.0
+
+servers:
+  - url: https://api.1611.social
+  
+# Add security definitions for authorization tokens
+security:
+ - bearerAuth:
+    type: apiKey
+    name: Authorization
+    in: header
+
+paths:
+  /verses:
+    get:
+      summary: Get verses by reference.
+      description: Retrieve a list of verses by providing a verse reference or range.
+      parameters:
+        - name: verse_reference
+          in: query
+          description: The verse reference, e.g., "1cor5:1,2cor1:2-5".
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of verses in JSON format.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    book:
+                      type: string
+                    chapter:
+                      type: integer
+                    verse:
+                      type: integer
+                    text:
+                      type: string
+    post:
+      summary: Submit sermon information.
+      description: Submit details of a sermon for review. Requires authorization.
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: Authorization
+          in: header
+          description: Bearer token for authorization.
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                title:
+                  type: string
+                url:
+                  type: string
+                preacher:
+                  type: string
+                date_preached:
+                  type: string
+                  format: date
+                church_name:
+                  type: string
+                denomination:
+                  type: string
+      responses:
+        '201':
+          description: Sermon submitted successfully.
+          content: {}
+        '401':
+          description: Unauthorized access.
+
+  /verses/{verse_id}:
+    get:
+      summary: Get verse by internal ID.
+      description: Retrieve a specific verse using its internal ID.
+      parameters:
+        - name: verse_id
+          in: path
+          description: The internal ID of the verse.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Verse details in JSON format.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  book:
+                    type: string
+                  chapter:
+                    type: integer
+                  verse:
+                    type: integer
+                  text:
+                    type: string
+
+  /search:
+    get:
+      summary: Search verses by keyword.
+      description: Return a list of verses matching a keyword search.
+      parameters:
+        - name: query
+          in: query
+          description: The keyword to search for.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of verses in JSON format.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    book:
+                      type: string
+                    chapter:
+                      type: integer
+                    verse:
+                      type: integer
+                    text:
+                      type: string
+
+  /search/semantic:
+    get:
+      summary: Search verses using semantic search.
+      description: Return a list of verses "most like" a query text. Requires authorization.
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: Authorization
+          in: header
+          description: Bearer token for authorization.
+          required: true
+          schema:
+            type: string
+        - name: query
+          in: query
+          description: The query text.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of verses in JSON format.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    book:
+                      type: string
+                    chapter:
+                      type: integer
+                    verse:
+                      type: integer
+                    text:
+                      type: string
+
+  /verses/{verse_reference}/like:
+    get:
+      summary: Find similar verses.
+      description: Return a list of verses similar to the provided reference.
+      parameters:
+        - name: verse_reference
+          in: path
+          description: The verse reference for comparison.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of similar verses in JSON format.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    book:
+                      type: string
+                    chapter:
+                      type: integer
+                    verse:
+                      type: integer
+                    text:
+                      type: string
+                    similarity_score:
+                      type: number
+                      description: Measure of similarity with the reference verse.
+
+  /sermons:
+    get:
+      summary: Get sermons referencing a verse.
+      description: Retrieve sermons containing a specific verse reference.
+      parameters:
+        - name: verse_reference
+          in: query
+          description: The verse reference to search for.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of sermons in JSON format.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    title:
+                      type: string
+                    url:
+                      type: string
+                    preacher:
+                      type: string
+                    date_preached:
+                      type: string
+                      format: date
+                    church_name:
+                      type: string
+                    denomination:
+                      type: string