feat: add swagger annotation (pathwar#56)

feat: add swagger annotation

Makefile

@@ -24,7 +24,7 @@ GENERATED_FILES = \
 	$(GENERATED_PB_FILES) \
 	$(PWCTL_OUT_FILES) \
 	swagger.yaml
-PROTOC_OPTS = -I/protobuf:vendor:.
+PROTOC_OPTS = -I/protobuf:vendor/github.com/grpc-ecosystem/grpc-gateway:vendor:.
 RUN_OPTS ?=
 
 ##

server/server.proto

@@ -5,13 +5,95 @@ package pathwar.server;
 import "google/api/annotations.proto";
 import "entity/entity.proto";
 import "github.com/gogo/protobuf/gogoproto/gogo.proto";
+import "protoc-gen-swagger/options/annotations.proto";
 //import "google/protobuf/timestamp.proto";
 
 option go_package = "pathwar.pw/server";
 option (gogoproto.sizer_all) = true;
 option (gogoproto.marshaler_all) = true;
 option (gogoproto.unmarshaler_all) = true;
 
+option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
+  host: "api.pathwar.net";
+  base_path: "/";
+  info: {
+    title: "Pathwar API";
+    version: "1.0",
+    contact: {
+      name: "Pathwar Team";
+      url: "https://github.com/pathwar/pathwar";
+      email: "[email protected]";
+    };
+    license: {
+      name: "Apache-2.0";
+      url: "https://github.com/pathwar/pathwar/blob/master/LICENSE";
+    };
+  };
+  external_docs: {
+    url: "https://github.com/pathwar/pathwar";
+    description: "More about Pathwar";
+  };
+  //schemes: HTTP;
+  schemes: HTTPS;
+  schemes: WSS;
+  consumes: "application/json";
+  produces: "application/json";
+
+  security_definitions: {
+    security: {
+      key: "BasicAuth";
+      value: {
+        type: TYPE_BASIC;
+      };
+    };
+    security: {
+      key: "ApiKeyAuth";
+      value: {
+        type: TYPE_API_KEY;
+        in: IN_HEADER;
+        name: "X-API-Key";
+      };
+    };
+  };
+  security: {
+    security_requirement: {
+      key: "BasicAuth";
+      value: {};
+    };
+    security_requirement: {
+      key: "ApiKeyAuth";
+      value: {};
+    };
+  };
+  responses: {
+    key: "403";
+    value: {
+      description: "Returned when the user does not have permission to access the resource.";
+    };
+  };
+  responses: {
+    key: "404";
+    value: {
+      description: "Returned when the resource does not exist.";
+      schema: {
+        json_schema: {
+          type: STRING;
+        };
+      };
+    };
+  };
+  responses: {
+    key: "418";
+    value: {
+      description: "I'm a teapot.";
+      schema: {
+        json_schema: {
+          ref: ".grpc.gateway.examples.examplepb.NumericEnum";
+        };
+      };
+    };
+  };
+};
 
 service Server {
 
@@ -74,13 +156,20 @@ service Server {
   };
 }
 
-message Void {}
+// Void is an empty message
+message Void {
+  option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
+    example: { value: '{}' };
+  };
+}
 
+// AuthenticateInput contains everything (credentials) to authenticate a user and create a new session.
 message AuthenticateInput {
   string username = 1;
   string password = 2;
 }
 
+// AuthenticateOutput contains a session token (JWT).
 message AuthenticateOutput {
   string token = 1;
 }

server/svc.go

@@ -1,6 +1,9 @@
 package server
 
 import "github.com/jinzhu/gorm"
+import "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/options"
+
+var _ = options.E_Openapiv2Swagger
 
 type svc struct {
 	jwtKey []byte