From 8b4e8970d2f87fc1c12e51092b98ca27be3d74ba Mon Sep 17 00:00:00 2001
From: Tyler <tyler@dinsmoor.us>
Date: Mon, 13 May 2024 14:41:35 -0700
Subject: [PATCH] Begin OpenAPI Specification

---
 .gitignore       |   3 +
 doc/openapi.yaml | 247 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 250 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 doc/openapi.yaml

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..19ab9be
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+__pycache__
+*.log
+
diff --git a/doc/openapi.yaml b/doc/openapi.yaml
new file mode 100644
index 0000000..bb92aff
--- /dev/null
+++ b/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
\ No newline at end of file