auto-generated API documents

Makefile.d/proto.mk

@@ -64,14 +64,25 @@ proto/gen/code: \
 	buf generate
 	make proto/replace
 
-proto/gen/api/docs: $(PROTO_API_DOCS)
+proto/gen/api/docs: \
+	proto/gen/api/docs/payload \
+	$(PROTO_API_DOCS)
 
-$(ROOTDIR)/apis/docs/v1/%.md: $(ROOTDIR)/apis/proto/v1/vald/%.proto
+proto/gen/api/docs/payload: $(ROOTDIR)/apis/docs/v1/payload.md.tmpl
+
+$(ROOTDIR)/apis/docs/v1/payload.md.tmpl: $(ROOTDIR)/apis/proto/v1/payload/payload.proto $(ROOTDIR)/apis/docs/v1/payload.tmpl
+	@$(call green, "generating payload  v1...")
+	buf generate --template=apis/docs/buf.gen.payload.yaml --path apis/proto/v1/payload/payload.proto
+
+$(ROOTDIR)/apis/docs/v1/%.md: $(ROOTDIR)/apis/proto/v1/vald/%.proto $(ROOTDIR)/apis/docs/v1/payload.md.tmpl $(ROOTDIR)/apis/docs/v1/doc.tmpl
 	@$(call green, "generating documents for API v1...")
-	buf generate --template=buf.gen.doc.yaml --path $(subst $(ROOTDIR)/,,$<)
+	buf generate --template=apis/docs/buf.gen.tmpl.yaml --path $(subst $(ROOTDIR)/,,$<)
+	cat apis/docs/v1/payload.md.tmpl apis/docs/v1/_doc.md.tmpl > apis/docs/v1/doc.md.tmpl
+	@sleep 1
+	buf generate --template=apis/docs/buf.gen.doc.yaml
 	@sleep 1
-	mv $(ROOTDIR)/apis/docs/v1/vald/tmp.md $@
-	rmdir $(ROOTDIR)/apis/docs/v1/vald
+	mv $(ROOTDIR)/apis/docs/v1/doc.md $@
+	rm apis/docs/v1/*doc.md.tmpl
 
 proto/replace:
 	find $(ROOTDIR)/apis/grpc/* -name '*.go' | xargs -P$(CORES) sed -i -E "s%google.golang.org/grpc/codes%$(GOPKG)/internal/net/grpc/codes%g"

buf.gen.doc.yaml → apis/docs/buf.gen.doc.yaml

@@ -23,5 +23,5 @@ managed:
       value: github.com/vdaas/vald/apis/grpc
 plugins:
   - local: protoc-gen-doc
-    out: apis/docs
-    opt: apis/docs/v1/docs.md.tmpl,tmp.md,source_relative
+    out: apis/docs/v1
+    opt: apis/docs/v1/doc.md.tmpl,doc.md

apis/docs/buf.gen.payload.yaml

@@ -0,0 +1,27 @@
+#
+# Copyright (C) 2019-2024 vdaas.org vald team <[email protected]>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+version: v2
+managed:
+  disable:
+    - file_option: go_package
+      module: buf.build/googleapis/googleapis
+  override:
+    - file_option: go_package_prefix
+      value: github.com/vdaas/vald/apis/grpc
+plugins:
+  - local: protoc-gen-doc
+    out: apis/docs/v1
+    opt: apis/docs/v1/payload.tmpl,payload.md.tmpl

apis/docs/buf.gen.tmpl.yaml

@@ -0,0 +1,27 @@
+#
+# Copyright (C) 2019-2024 vdaas.org vald team <[email protected]>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+version: v2
+managed:
+  disable:
+    - file_option: go_package
+      module: buf.build/googleapis/googleapis
+  override:
+    - file_option: go_package_prefix
+      value: github.com/vdaas/vald/apis/grpc
+plugins:
+  - local: protoc-gen-doc
+    out: apis/docs/v1
+    opt: apis/docs/v1/doc.tmpl,_doc.md.tmpl

apis/docs/v1/doc.tmpl

@@ -0,0 +1,53 @@
+{{ range .Files -}}
+{{ range .Services -}}
+# Vald {{ .Name }} APIs
+
+## Overview
+
+{{.Description}}
+
+```rpc
+service {{.Name}} {
+
+{{ range .Methods }}  rpc {{ .Name }}({{ .RequestFullType }}) returns ({{ .ResponseFullType }}) {}
+{{ end }}
+}
+```
+
+{{ range .Methods -}}
+## {{ .Name }} RPC
+
+{{ .Description }}
+
+### Input
+
+- the scheme of `{{ .RequestFullType }}`
+
+  ```rpc
+{{ printf "{{- template \"scheme.%s\" }}" .RequestFullType }}
+  ```
+{{ printf "{{ template \"field.%s\" }}" .RequestFullType }}
+
+### Output
+
+- the scheme of `{{ .ResponseFullType }}`
+
+  ```rpc
+{{ printf "{{- template \"scheme.%s\" }}" .ResponseFullType }}
+  ```
+{{ printf "{{ template \"field.%s\" }}" .ResponseFullType }}
+
+### Status Code
+
+| code | desc.             |
+| :--: | :---------------- |
+| 0    | OK                |
+| 1    | CANCELLED         |
+| 3    | INVALID_ARGUMENT  |
+| 4    | DEADLINE_EXCEEDED |
+| 5    | NOT_FOUND         |
+| 13   | INTERNAL          |
+
+{{ end -}}
+{{- end -}}
+{{- end -}}