cleanup openapi schema

4 files changed, 54 insertions, 25 deletions

diff --git a/golang/.gitignore b/golang/.gitignore
index 0fe55f3e..3caab53e 100644
--- a/golang/.gitignore
+++ b/golang/.gitignore
@@ -1,2 +1,3 @@
 vendor/
 coverage.txt
+fatcat-openapi2.json
diff --git a/golang/README.md b/golang/README.md
index 667b9a2e..9bcfdfb5 100644
--- a/golang/README.md
+++ b/golang/README.md
@@ -42,6 +42,8 @@ In early development, we'll make at least the following simplifications:
 
 ## OpenAPI Code Generation
 
+    cat fatcat-openapi2.yml | python3 -c 'import sys, yaml, json; json.dump(yaml.load(sys.stdin), sys.stdout, indent=4)' > fatcat-openapi2.json
+
 Install the go-swagger tool:
 
     go get -u github.com/go-swagger/go-swagger/cmd/swagger
@@ -49,8 +51,15 @@ Install the go-swagger tool:
 
 "Simple" server:
 
-    swagger generate server -A Fatcat -f fatcat-openapi2.yml
+    swagger generate server -A Fatcat -f fatcat-openapi2.json
 
 "Custom" server:
 
-    swagger generate server -A fatcat -f ./fatcat-openapi2.yml --exclude-main -t gen
+    swagger generate server -A fatcat -f ./fatcat-openapi2.json --exclude-main -t gen
+
+## Future
+
+Could refactor the API side to use gRPC and grpc-gateway instead of swagger
+(which would result in a compatible REST JSON interface). For faster bots and
+import, and lower latency between webface and backend.
+
diff --git a/golang/fatcat-openapi2.yml b/golang/fatcat-openapi2.yml
index a00780f0..5d22213f 100644
--- a/golang/fatcat-openapi2.yml
+++ b/golang/fatcat-openapi2.yml
@@ -9,13 +9,23 @@ schemes: [http]
 basePath: /v0
 host: api.fatcat.wiki
 consumes:
-- application/json
+  - application/json
 produces:
-- application/json
+  - application/json
 
-# TODO: try to make this work:
-#x-entity-props: &ENTITYPROPS
-#<<: *ENTITYPROPS
+# Common properties across entities
+x-entity-props: &ENTITYPROPS
+  state:
+    type: string
+    enum: ["wip", "active", "redirect", "deleted"]
+  ident:
+    type: string
+    #format: uuid
+  revision:
+    type: integer
+  redirect:
+    type: string
+    #format: uuid
 
 
 definitions:
@@ -33,35 +43,37 @@ definitions:
     properties:
       message:
         type: string
-  creator_entity:
+  release_entity:
     type: object
     required:
       - ident
       - state
-      - name
     properties:
-      state: 
-        type: string
-        enum: ["wip", "active", "redirect", "deleted"]
-      ident:
+      <<: *ENTITYPROPS
+      name:
         type: string
-        #format: uuid
-      revision:
-        type: integer
-      redirect:
+      orcid:
         type: string
-        # format: uuid
+        #format: custom
+  creator_entity:
+    type: object
+    required:
+      - ident
+      - state
+      - name
+    properties:
+      <<: *ENTITYPROPS
       name:
         type: string
       orcid:
         type: string
-        # format: custom
+        #format: custom
   editor:
     type: object
     required:
       - username
     properties:
-      username: 
+      username:
         type: string
   editgroup:
     type: object
@@ -69,20 +81,20 @@ definitions:
       - id
       - editor_id
     properties:
-      id: 
+      id:
         type: integer
-      editor_id: 
+      editor_id:
         type: integer
   changelogentry:
     type: object
     required:
       - index
     properties:
-      index: 
+      index:
         type: integer
-      editgroup_id: 
+      editgroup_id:
         type: integer
-      timestamp: 
+      timestamp:
         type: string
         format: date-time
 
diff --git a/golang/regen.sh b/golang/regen.sh
new file mode 100755
index 00000000..366314a0
--- /dev/null
+++ b/golang/regen.sh
@@ -0,0 +1,7 @@
+#!/bin/bash
+
+set -xeo pipefail
+
+cat fatcat-openapi2.yml | python3 -c 'import sys, yaml, json; json.dump(yaml.load(sys.stdin), sys.stdout, indent=4)' > fatcat-openapi2.json
+swagger generate server -A fatcat -f ./fatcat-openapi2.json --exclude-main -t gen
+rm fatcat-openapi2.json