From 8b027a48e824ef0dbb0c57dabbdce5276addf2e6 Mon Sep 17 00:00:00 2001
From: Ben Sima <ben@bensima.com>
Date: Fri, 23 May 2025 16:15:12 -0400
Subject: [PATCH] imp: web: further document the api endpoints

---
 hledger-web/config/openapi.yaml | 103 +++++++++++++++++++++++---------
 1 file changed, 76 insertions(+), 27 deletions(-)

diff --git a/hledger-web/config/openapi.yaml b/hledger-web/config/openapi.yaml
index dad2d08b9..cd6ec7446 100644
--- a/hledger-web/config/openapi.yaml
+++ b/hledger-web/config/openapi.yaml
@@ -1,33 +1,55 @@
+# This is an OpenAPI Spec of hledger-web's JSON-over-HTTP API:
+#
+# https://hledger.org/hledger-web.html#json-api
+#
+# Originally generated by openapi-devtools:
+#
+# https://github.com/AndrewWalsh/openapi-devtools
+# https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/haskell-yesod.md
+#
+# and then modified by hand.
+
+
 openapi: 3.1.0
+
 info:
-  title: OpenAPI Specification
-  description: "Basic description of [hledger-web's JSON-over-HTTP API](https://hledger.org/hledger-web.html#json-api).\
-    \ A specification generated by [openapi-devtools](https://github.com/AndrewWalsh/openapi-devtools).\
-    \ Contains 7 endpoints."
+  title: hledger-web API
+  description: >
+    Provides interaction with hledger, the plaintext accounting tool powered by
+    Haskell. Lookup account details, balances, commodity prices, and
+    transactions.
   version: 1.0.0
+
 servers:
-- url: /
+- url: http://127.0.0.1:5000
+  description: Locally hosted server for hledger-web API
+
+
 paths:
+
   /version:
     get:
-      summary: /version
-      description: "**Host**: http://127.0.0.1:5000"
+      summary: The hledger version
+      description: Returns the hledger version that powers this API as a SemVer string.
+      operationId: hledger_version
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema: {}
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
+
   /accountnames:
     get:
-      summary: /accountnames
-      description: "**Host**: http://127.0.0.1:5000"
+      summary: Account names
+      description: Returns all of the account names in a JSON array
+      operationId: hledger_account_names
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema:
@@ -35,13 +57,16 @@ paths:
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
+
   /transactions:
     get:
-      summary: /transactions
-      description: "**Host**: http://127.0.0.1:5000"
+      summary: Transaction query
+      description: >
+        Queries the journal for transactions (txs). Returns a list of JSON
+        objects describing the tx postings.
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema:
@@ -180,13 +205,17 @@ paths:
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
+
   /prices:
     get:
-      summary: /prices
-      description: "**Host**: http://127.0.0.1:5000"
+      summary: Commodity prices
+      description: >
+        Queries the journal for commodity prices. Returns a list of JSON objects
+        with commodity price information.
+      operationId: hledger_commodity_prices
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema:
@@ -212,13 +241,17 @@ paths:
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
+
   /commodities:
     get:
-      summary: /commodities
-      description: "**Host**: http://127.0.0.1:5000"
+      operationId: hledger_commodity_symbols
+      summary: Commodity symbols
+      description: >
+        List all tracked commodities in the ledger. Returns a JSON list of
+        strings of commodity symbols
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema:
@@ -226,13 +259,17 @@ paths:
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
+
   /accounts:
     get:
-      summary: /accounts
-      description: "**Host**: http://127.0.0.1:5000"
+      operationId: hledger_accounts
+      summary: Account information
+      description: >
+        Queries the journal for account information. Returns a JSON list of
+        account objects
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema:
@@ -407,13 +444,24 @@ paths:
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
-  /accounttransactions/1:
+
+  /accounttransactions/{name}:
     get:
-      summary: /accounttransactions/1
-      description: "**Host**: http://127.0.0.1:5000"
+      operationId: hledger_account_txs
+      summary: Account transactions
+      description: >
+        List transactions in the requested account. Returns a JSON list of
+        transaction objects (txs).
+      parameters:
+        - name: name
+          in: path
+          required: true
+          description: The account name to lookup
+          schema:
+            type: string
       responses:
         "200":
-          description: ""
+          description: Successful Response
           content:
             application/json:
               schema:
@@ -548,6 +596,7 @@ paths:
       security:
       - apikey_cookie__session: []
       - apikey_header_cookie: []
+
 components:
   schemas: {}
   securitySchemes: