feat: set format for path param and add docs (#121)

* feat: set format for path param and add docs

* test: add field format for path param case

Author: sashamelentyev

README.md

@@ -18,6 +18,7 @@ protoc --oas_out=. service.proto
 
 - support [API annotations](https://github.com/googleapis/googleapis/blob/master/google/api/annotations.proto) in methods
 - support [field behavior](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) in message field description
+- support [field info](https://github.com/googleapis/googleapis/blob/master/google/api/field_info.proto) in message field description
 
 # Generate OpenAPI
 
@@ -374,3 +375,68 @@ components:
     Empty:
       type: object
 ```
+
+## Set field format
+
+```protobuf title="service.proto"
+syntax = "proto3";
+
+package service.v1;
+
+option go_package = "service/v1;service";
+
+import "google/api/annotations.proto";
+import "google/api/field_info.proto";
+
+service Service {
+  rpc GetItem(GetItemRequest) returns (Item) {
+    option (google.api.http) = {
+      get: "/api/v1/items/{id}"
+    };
+  }
+}
+
+message GetItemRequest {
+  string id = 1 [(google.api.field_info).format = UUID4]; // <--
+}
+
+message Item {
+  string id = 1 [(google.api.field_info).format = UUID4]; // <--
+  string name = 2;
+}
+```
+
+```yaml title="openapi.yaml"
+openapi: 3.1.0
+info:
+  title: ""
+  version: ""
+paths:
+  /api/v1/items/{id}:
+    get:
+      operationId: getItem
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid # <--
+      responses:
+        "200":
+          description: service.v1.Service.GetItem response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Item'
+components:
+  schemas:
+    Item:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid # <--
+        name:
+          type: string
+```

example/message.proto

@@ -41,7 +41,10 @@ message GetItemsResponse {
 }
 
 message GetItemRequest {
-  string id = 1 [(google.api.field_behavior) = REQUIRED];
+  string id = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.field_info).format = UUID4
+  ];
 }
 
 message UpdateItemRequest {

example/openapi.yaml

@@ -50,6 +50,7 @@ paths:
           required: true
           schema:
             type: string
+            format: uuid
       responses:
         "200":
           description: service.v1.Service.GetItem response

internal/gen/_golden/field_format.json

@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"","version":""},"paths":{"/api/v1/items/{id}":{"get":{"operationId":"getItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"crud.v1.Crud.GetItem response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}}}}}},"components":{"schemas":{"Item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ipv4":{"type":"string","format":"ipv4"},"ipv6":{"type":"string","format":"ipv6"},"ip":{"type":"string","format":"ip"}},"required":["id","ipv4","ipv6","ip"]}}}}
+{"openapi":"3.1.0","info":{"title":"","version":""},"paths":{"/api/v1/items/{id}":{"get":{"operationId":"getItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"crud.v1.Crud.GetItem response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}}}}}},"components":{"schemas":{"Item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ipv4":{"type":"string","format":"ipv4"},"ipv6":{"type":"string","format":"ipv6"},"ip":{"type":"string","format":"ip"}},"required":["id","ipv4","ipv6","ip"]}}}}

internal/gen/_golden/field_format.yaml

@@ -12,6 +12,7 @@ paths:
           required: true
           schema:
             type: string
+            format: uuid
       responses:
         "200":
           description: crud.v1.Crud.GetItem response

internal/gen/_testdata/field_format.textproto

@@ -57,7 +57,8 @@ proto_file: {
       type: TYPE_STRING
       json_name: "id"
       options:{
-        [google.api.field_behavior]:REQUIRED
+        [google.api.field_behavior]:REQUIRED,
+        [google.api.field_info]:{format:UUID4}
       }
     }
   }

internal/gen/generator.go

@@ -354,6 +354,8 @@ func (g *Generator) mkParameter(in, name string, f *protogen.Field) (*ogen.Param
 		return nil, errors.Wrapf(err, "generate %s parameter %q", in, f.Desc.Name())
 	}
 
+	setFieldFormat(s, f.Desc.Options())
+
 	p := ogen.NewParameter().
 		SetIn(in).
 		SetName(name).