chore(milpacs): deprecate GetUserViaKeycloakId rpc + keycloak_id fields (#97)

Phase 1 of 2 — adds deprecation surface only, no behavior change.

- `option deprecated = true;` on the RPC; `deprecated: true` in the
  openapiv2_operation so swagger UI flags the endpoint.
- `[deprecated = true]` on `keycloak_id` in `KeycloakIdRequest`, `Profile`,
  `LiteProfile`. Propagates to .pb.go getters as `// Deprecated:` comments.
- Enable protoc-gen-openapiv2 `enable_field_deprecation=true` so the
  `keycloakId` path parameter renders deprecated in swagger.
- Pin the contract: descriptor-level deprecation test in proto/, swagger
  surface test in openapi/. Existing TestGetUserViaKeycloakId_* unchanged.

Schema-property `deprecated` is OpenAPI 3.0 only — Swagger 2.0 has no slot
for it, so the doc-side signal lives on the op + path param. Removal is
tracked in #100.

Author: SyniRon

buf.gen.yaml

@@ -11,3 +11,4 @@ plugins:
     opt: paths=source_relative
   - local: protoc-gen-openapiv2
     out: openapi/assets
+    opt: enable_field_deprecation=true

openapi/assets/milpacs.swagger.json

@@ -107,12 +107,14 @@
             "name": "keycloakId",
             "in": "path",
             "required": true,
+            "deprecated": true,
             "type": "string"
           }
         ],
         "tags": [
           "Roster, Milpacs, Keycloak"
-        ]
+        ],
+        "deprecated": true
       }
     },
     "/api/v1/milpacs/awol": {

openapi/openapi_test.go

@@ -0,0 +1,39 @@
+package openapi
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Phase 1 deprecation surface for GetUserViaKeycloakId (issue #97).
+// OpenAPI 2.0 supports `deprecated` on operations and parameters but NOT on
+// schema properties (added in OpenAPI 3.0). This test pins what the
+// swagger.json — i.e. the API doc surface — actually advertises to consumers.
+// Schema-property deprecation for Profile.keycloak_id / LiteProfile.keycloak_id
+// is asserted via the proto descriptor in proto_deprecation_test.go.
+func TestMilpacsSwagger_DeprecatesKeycloakIdSurface(t *testing.T) {
+	raw, err := Files.ReadFile("assets/milpacs.swagger.json")
+	require.NoError(t, err)
+
+	var spec struct {
+		Paths map[string]map[string]struct {
+			Deprecated bool `json:"deprecated"`
+			Parameters []struct {
+				Name       string `json:"name"`
+				Deprecated bool   `json:"deprecated"`
+			} `json:"parameters"`
+		} `json:"paths"`
+	}
+	require.NoError(t, json.Unmarshal(raw, &spec))
+
+	op, ok := spec.Paths["/api/v1/milpac/keycloak/{keycloakId}"]["get"]
+	require.True(t, ok, "GET /api/v1/milpac/keycloak/{keycloakId} missing from spec")
+	assert.True(t, op.Deprecated, "GetUserViaKeycloakId op must be deprecated")
+
+	require.Len(t, op.Parameters, 1)
+	assert.Equal(t, "keycloakId", op.Parameters[0].Name)
+	assert.True(t, op.Parameters[0].Deprecated, "keycloakId path parameter must be deprecated")
+}

proto/deprecation_test.go

@@ -0,0 +1,47 @@
+package proto
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/reflect/protoreflect"
+	"google.golang.org/protobuf/types/descriptorpb"
+)
+
+// Phase 1 deprecation contract for GetUserViaKeycloakId (issue #97).
+// Asserts the proto-level deprecation flags that downstream consumers
+// (generated code, descriptors, linters) actually observe. The OpenAPI
+// surface is asserted in openapi/openapi_test.go.
+func TestKeycloakIdDeprecationContract(t *testing.T) {
+	svc := File_milpacs_proto.Services().ByName("MilpacService")
+	require.NotNil(t, svc, "MilpacService missing from descriptor")
+
+	rpc := svc.Methods().ByName("GetUserViaKeycloakId")
+	require.NotNil(t, rpc, "GetUserViaKeycloakId rpc missing")
+	assert.True(t, methodDeprecated(rpc), "GetUserViaKeycloakId must be deprecated")
+
+	for _, c := range []struct {
+		msg, field string
+	}{
+		{"KeycloakIdRequest", "keycloak_id"},
+		{"Profile", "keycloak_id"},
+		{"LiteProfile", "keycloak_id"},
+	} {
+		msg := File_milpacs_proto.Messages().ByName(protoreflect.Name(c.msg))
+		require.NotNil(t, msg, "%s missing from descriptor", c.msg)
+		f := msg.Fields().ByName(protoreflect.Name(c.field))
+		require.NotNil(t, f, "%s.%s missing from descriptor", c.msg, c.field)
+		assert.True(t, fieldDeprecated(f), "%s.%s must be deprecated", c.msg, c.field)
+	}
+}
+
+func methodDeprecated(m protoreflect.MethodDescriptor) bool {
+	opts, ok := m.Options().(*descriptorpb.MethodOptions)
+	return ok && opts.GetDeprecated()
+}
+
+func fieldDeprecated(f protoreflect.FieldDescriptor) bool {
+	opts, ok := f.Options().(*descriptorpb.FieldOptions)
+	return ok && opts.GetDeprecated()
+}

proto/milpacs.pb.go

@@ -81,13 +81,15 @@ service MilpacService {
     };
   };
   rpc GetUserViaKeycloakId(KeycloakIdRequest) returns (Profile){
+    option deprecated = true;
     option(google.api.http) = {
       get: "/api/v1/milpac/keycloak/{keycloak_id}"
     };
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
       summary: "Get a Milpac profile via keycloak ID"
       description: "Get all milpac Profile data for a given user via their Keycloak ID"
       tags: "Roster, Milpacs, Keycloak"
+      deprecated: true
     };
   };
   rpc GetUserViaDiscordId(DiscordIdRequest) returns (Profile){
@@ -239,7 +241,7 @@ message ProfileRequest {
 }
 
 message KeycloakIdRequest {
-  string keycloak_id = 1;
+  string keycloak_id = 1 [deprecated = true];
 }
 
 message DiscordIdRequest {
@@ -269,7 +271,7 @@ message Profile {
   repeated Award awards = 9;
   string join_date = 10;
   string promotion_date = 11;
-  string keycloak_id = 12;
+  string keycloak_id = 12 [deprecated = true];
   string discord_id = 13;
   string last_forum_post_date = 14;
   string mos = 15;
@@ -319,7 +321,7 @@ message LiteProfile {
   repeated Position secondaries = 7;
   string join_date = 8;
   string promotion_date = 9;
-  string keycloak_id = 10;
+  string keycloak_id = 10 [deprecated = true];
   string discord_id = 11;
   string award_date = 12;
   string record_date = 13;