docs: added OpenAPI definition and reference in the readme

README.md

@@ -43,6 +43,12 @@ Converts an Anilist user watching list to a custom list format which *arr apps s
 It works by fetching the user info directly from Anilist thanks to its API, and
 converts the IDs using community-provided mappings.
 
+Try it out on a live instance at `https://anilistarr.fly.dev/`. For API details
+check either the [source Swagger definition](./swagger.yaml) or the generated
+[online version here][swagger-ui].
+
+[swagger-ui]: https://editor.swagger.io/?url=https://raw.githubusercontent.com/wwmoraes/anilistarr/master/swagger.yaml
+
 ## 🏁 Getting Started
 
 Clone the repository and use `go run ./cmd/handler/...` to get the REST API up.
@@ -54,9 +60,18 @@ Explain how to run the automated tests for this system.
 ## 🎈 Usage
 
 Configuration in general is a WIP. The code supports distinct storage and cache
-options and even has built-in support for Redis and Bolt as caches already.
-The handler needs flags/configuration file support to allow switching at
-runtime.
+options and has built-in support for different caches and stores. The handler
+needs flags/configuration file support to allow switching at runtime.
+
+Implemented solutions:
+
+- Cache
+  - Badger
+  - Bolt (no TTL support tho)
+  - Redis
+- Store
+  - Badger
+  - SQL (model generated for SQLite, should work for others but YMMV)
 
 ## 🚀 Deployment
 

swagger.yaml

@@ -0,0 +1,68 @@
+openapi: 3.1.0
+info:
+  title: Anilistarr
+  description: |-
+    Converts an Anilist user watching list to a custom list format which *arr apps support.
+  # termsOfService: http://swagger.io/terms/
+  contact:
+    email: anilistarr@artero.dev
+  license:
+    name: MIT
+    url: https://raw.githubusercontent.com/wwmoraes/anilistarr/master/LICENSE
+  version: 0.1.0
+externalDocs:
+  description: Find out more about the project
+  url: http://github.com/wwmoraes/anilistarr
+servers:
+  - url: https://anilistarr.fly.dev
+paths:
+  /user:
+    get:
+      parameters:
+        - name: name
+          in: query
+          content:
+            text/plain:
+              example: wwmoraes
+      responses:
+        200:
+          description: user found
+          content:
+            text/plain:
+              example: 1234
+        500:
+          description: either a rate limit or other issue with the upstream tracker happened
+          content:
+            text/plain:
+              example: |
+                failed to get user ID: ...
+  /list:
+    get:
+      parameters:
+        - name: username
+          in: query
+          content:
+            text/plain:
+              example: wwmoraes
+      responses:
+        200:
+          description: media list for the given user
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CustomList'
+        500:
+          description: either a rate limit or other issue with the upstream tracker happened
+          content:
+            text/plain:
+              example: |-
+                failed to get user ID: ...
+components:
+  schemas:
+    CustomList:
+      type: array
+      items:
+        type: object
+        properties:
+          TvdbID:
+            type: number