fix: add api docs and http handler for openapi files (#1526)

* tests

* chore: set vars for platform in dockerfile

* simplyfy generate

* correct dockerfile

* add openapi to gitignore

* object files

* protos

* update protoc version

* admin only secuity missing

* texts

* start secutiry

* add handler

* add description

* add descriptions and remove adddress

* default limit

* add mapping for openapi

* generate statik for openapi

* remove address converter

* executable

* operator test

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

.gitignore

@@ -47,10 +47,8 @@ tmp/
 console/src/app/proto/generated/
 
 #generated filed
-pkg/grpc/*/*.pb*.*
-pkg/grpc/*/*.swagger.json
-pkg/grpc/*/mock/*.mock.go
 **.pb.go
 **.proto.mock.go
 **.pb.*.go
 **.gen.go 
+openapi/**/*.json

build/dockerfile

@@ -48,7 +48,7 @@ RUN curl https://raw.githubusercontent.com/envoyproxy/protoc-gen-validate/v0.4.1
     && curl https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/field_behavior.proto --create-dirs -o include/google/api/field_behavior.proto
 
 #zitadel protos
-COPY /proto/ include/.
+COPY proto/ include/.
 
 
 #######################
@@ -95,28 +95,38 @@ RUN npm run prodbuild
 #######################
 FROM golang:${GO_VERSION} as go-dep
 RUN mkdir -p src/github.com/caos/zitadel
-COPY . src/github.com/caos/zitadel/
+# copy mod definitions
-WORKDIR /go/src/github.com/caos/zitadel/
+COPY tools src/github.com/caos/zitadel/tools
+COPY ./go.* src/github.com/caos/zitadel
 
+# install all dependencies
+WORKDIR /go/src/github.com/caos/zitadel
 RUN go mod download
 RUN ./tools/install.sh
 
+FROM go-dep AS go-gen
+COPY --from=base /proto /proto
+COPY --from=base /usr/local/bin /usr/local/bin/.
+COPY build/zitadel/generate-grpc.sh build/zitadel/generate-grpc.sh
+COPY internal/protoc internal/protoc
+RUN build/zitadel/generate-grpc.sh
+
 #######################
 ## Go base build
 #######################
-FROM go-dep as go-base
+FROM go-gen as go-base
-COPY --from=base /proto /proto
+# copy all zitadel files
-COPY --from=base /usr/local/bin /usr/local/bin/.
+COPY . .
-RUN build/zitadel/generate-grpc.sh
 
 
 #######################
 ## copy for local dev
 #######################
 FROM scratch as go-copy
-COPY --from=go-base /go/src/github.com/caos/zitadel/pkg/grpc ./pkg/grpc
+COPY --from=go-gen /go/src/github.com/caos/zitadel/pkg/grpc ./pkg/grpc
-COPY --from=go-base /go/src/github.com/caos/zitadel/internal/protoc/protoc-gen-authoption/templates.gen.go ./internal/protoc/protoc-gen-authoption/templates.gen.go
+COPY --from=go-gen /go/src/github.com/caos/zitadel/openapi/v2/zitadel ./openapi/v2/zitadel
-COPY --from=go-base /go/src/github.com/caos/zitadel/internal/protoc/protoc-gen-authoption/authoption/options.pb.go ./internal/protoc/protoc-gen-authoption/authoption/options.pb.go
+COPY --from=go-gen /go/src/github.com/caos/zitadel/internal/protoc/protoc-gen-authoption/templates.gen.go ./internal/protoc/protoc-gen-authoption/templates.gen.go
+COPY --from=go-gen /go/src/github.com/caos/zitadel/internal/protoc/protoc-gen-authoption/authoption/options.pb.go ./internal/protoc/protoc-gen-authoption/authoption/options.pb.go
 
 
 #######################
@@ -149,7 +159,8 @@ RUN go get github.com/rakyll/statik \
     && ./build/console/generate-static.sh \
     && ./build/login/generate-static.sh \
     && ./build/notification/generate-static.sh \
-    && ./build/zitadel/generate-static.sh
+    && ./build/zitadel/generate-static.sh \
+    && ./build/zitadel/generate-openapi-static.sh
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=${BUILDARCH} go build -a -installsuffix cgo -ldflags '-extldflags "-static"' -o zitadel-linux-${BUILDARCH} cmd/zitadel/main.go
 
 

build/zitadel/generate-grpc.sh

@@ -9,27 +9,30 @@ ZITADEL_PATH=${GOPATH}/src/github.com/caos/zitadel
 GRPC_PATH=${ZITADEL_PATH}/pkg/grpc
 PROTO_PATH=/proto/include/zitadel
 
+# generate go stub and grpc code for all files
 protoc \
   -I=/proto/include/ \
   --go_out $GOPATH/src \
   --go-grpc_out $GOPATH/src \
-  $(find ${PROTO_PATH} -iname *.proto | grep -v "management|admin|auth")
+  $(find ${PROTO_PATH} -iname *.proto)
 
+# generate authoptions code from templates
 go-bindata \
   -pkg main \
   -prefix internal/protoc/protoc-gen-authoption \
   -o ${ZITADEL_PATH}/internal/protoc/protoc-gen-authoption/templates.gen.go \
   ${ZITADEL_PATH}/internal/protoc/protoc-gen-authoption/templates
 
+# install authoption proto compiler
 go install ${ZITADEL_PATH}/internal/protoc/protoc-gen-authoption
 
 # output folder for openapi v2
 mkdir -p ${OPENAPI_PATH}
 
+# generate additional output
+
 protoc \
   -I=/proto/include \
-  --go_out ${GOPATH}/src \
-  --go-grpc_out ${GOPATH}/src \
   --grpc-gateway_out ${GOPATH}/src \
   --grpc-gateway_opt logtostderr=true \
   --openapiv2_out ${OPENAPI_PATH} \
@@ -37,13 +40,13 @@ protoc \
   --authoption_out ${GRPC_PATH}/admin \
   --validate_out=lang=go:${GOPATH}/src \
   ${PROTO_PATH}/admin.proto
+
+# authoptions are generated into the wrong folder
 mv ${ZITADEL_PATH}/pkg/grpc/admin/zitadel/* ${ZITADEL_PATH}/pkg/grpc/admin
 rm -r ${ZITADEL_PATH}/pkg/grpc/admin/zitadel
 
 protoc \
   -I=/proto/include \
-  --go_out $GOPATH/src \
-  --go-grpc_out $GOPATH/src \
   --grpc-gateway_out ${GOPATH}/src \
   --grpc-gateway_opt logtostderr=true \
   --grpc-gateway_opt allow_delete_body=true \
@@ -53,13 +56,13 @@ protoc \
   --authoption_out ${GRPC_PATH}/management \
   --validate_out=lang=go:${GOPATH}/src \
   ${PROTO_PATH}/management.proto
+
+# authoptions are generated into the wrong folder
 mv ${ZITADEL_PATH}/pkg/grpc/management/zitadel/* ${ZITADEL_PATH}/pkg/grpc/management
 rm -r ${ZITADEL_PATH}/pkg/grpc/management/zitadel
 
 protoc \
   -I=/proto/include \
-  --go_out $GOPATH/src \
-  --go-grpc_out $GOPATH/src \
   --grpc-gateway_out ${GOPATH}/src \
   --grpc-gateway_opt logtostderr=true \
   --openapiv2_out ${OPENAPI_PATH} \
@@ -67,6 +70,8 @@ protoc \
   --authoption_out=${GRPC_PATH}/auth \
   --validate_out=lang=go:${GOPATH}/src \
   ${PROTO_PATH}/auth.proto
+
+# authoptions are generated into the wrong folder
 mv ${ZITADEL_PATH}/pkg/grpc/auth/zitadel/* ${ZITADEL_PATH}/pkg/grpc/auth
 rm -r ${ZITADEL_PATH}/pkg/grpc/auth/zitadel
 

build/zitadel/generate-openapi-static.sh

@@ -0,0 +1,5 @@
+#! /bin/sh
+
+set -eux
+
+go generate openapi/statik/generate.go

cmd/zitadel/main.go

@@ -9,6 +9,7 @@ import (
 	"github.com/caos/zitadel/internal/eventstore"
 	"github.com/caos/zitadel/internal/query"
 	metrics "github.com/caos/zitadel/internal/telemetry/metrics/config"
+	"github.com/caos/zitadel/openapi"
 
 	"github.com/caos/logging"
 
@@ -177,6 +178,11 @@ func startAPI(ctx context.Context, conf *Config, authZRepo *authz_repo.EsReposit
 		op := oidc.NewProvider(ctx, conf.API.OIDC, command, query, authRepo, conf.SystemDefaults.KeyConfig.EncryptionConfig, *localDevMode)
 		apis.RegisterHandler("/oauth/v2", op.HttpHandler())
 	}
+
+	openAPIHandler, err := openapi.Start()
+	logging.Log("ZITAD-8pRk1").OnError(err).Fatal("Unable to start openapi handler")
+	apis.RegisterHandler("/openapi/v2/swagger", openAPIHandler)
+
 	apis.Start(ctx)
 }
 

internal/api/grpc/user/converter.go

@@ -114,16 +114,6 @@ func ModelPhoneToPb(phone *model.Phone) *user_pb.Phone {
 	}
 }
 
-func ModelAddressToPb(address *model.Address) *user_pb.Address {
-	return &user_pb.Address{
-		Country:       address.Country,
-		Locality:      address.Locality,
-		PostalCode:    address.PostalCode,
-		Region:        address.Region,
-		StreetAddress: address.StreetAddress,
-	}
-}
-
 func GenderToDomain(gender user_pb.Gender) domain.Gender {
 	switch gender {
 	case user_pb.Gender_GENDER_DIVERSE:

openapi/handler.go

@@ -0,0 +1,19 @@
+package openapi
+
+import (
+	"net/http"
+
+	"github.com/rakyll/statik/fs"
+
+	_ "github.com/caos/zitadel/openapi/statik"
+)
+
+func Start() (http.Handler, error) {
+	statikFS, err := fs.NewWithNamespace("swagger")
+	if err != nil {
+		return nil, err
+	}
+	handler := &http.ServeMux{}
+	handler.Handle("/", http.FileServer(statikFS))
+	return handler, nil
+}

openapi/statik/generate.go

@@ -0,0 +1,3 @@
+package statik
+
+//go:generate statik -src=../v2/zitadel -dest=.. -ns=swagger

operator/zitadel/kinds/iam/zitadel/ambassador/adapt_test.go

@@ -76,6 +76,8 @@ func SetMappingsHTTP(
 	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, http.MgmtName, gomock.Any()).MinTimes(1).MaxTimes(1)
 	SetReturnResourceVersion(k8sClient, group, version, kind, namespace, http.OauthName, "")
 	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, http.OauthName, gomock.Any()).MinTimes(1).MaxTimes(1)
+	SetReturnResourceVersion(k8sClient, group, version, kind, namespace, http.OpenAPIName, "")
+	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, http.OpenAPIName, gomock.Any()).MinTimes(1).MaxTimes(1)
 }
 
 func SetMappingsGRPC(

operator/zitadel/kinds/iam/zitadel/ambassador/http/adapt.go

@@ -5,6 +5,7 @@ import (
 	"github.com/caos/orbos/pkg/kubernetes"
 	"github.com/caos/orbos/pkg/kubernetes/resources/ambassador/mapping"
 	"github.com/caos/orbos/pkg/labels"
+
 	"github.com/caos/zitadel/operator"
 	"github.com/caos/zitadel/operator/zitadel/kinds/iam/zitadel/configuration"
 )
@@ -17,6 +18,7 @@ const (
 	AuthorizeName  = "authorize-v1"
 	EndsessionName = "endsession-v1"
 	IssuerName     = "issuer-v1"
+	OpenAPIName    = "openapi"
 )
 
 func AdaptFunc(
@@ -67,6 +69,11 @@ func AdaptFunc(
 		return nil, nil, err
 	}
 
+	destroySwagger, err := mapping.AdaptFuncToDestroy(namespace, OpenAPIName)
+	if err != nil {
+		return nil, nil, err
+	}
+
 	destroyers := []operator.DestroyFunc{
 		operator.ResourceDestroyToZitadelDestroy(destroyAdminR),
 		operator.ResourceDestroyToZitadelDestroy(destroyMgmtRest),
@@ -75,6 +82,7 @@ func AdaptFunc(
 		operator.ResourceDestroyToZitadelDestroy(destroyAuthorize),
 		operator.ResourceDestroyToZitadelDestroy(destroyEndsession),
 		operator.ResourceDestroyToZitadelDestroy(destroyIssuer),
+		operator.ResourceDestroyToZitadelDestroy(destroySwagger),
 	}
 
 	return func(k8sClient kubernetes.ClientInt, queried map[string]interface{}) (operator.EnsureFunc, error) {
@@ -208,6 +216,22 @@ func AdaptFunc(
 				return nil, err
 			}
 
+			queryOpenAPI, err := mapping.AdaptFuncToEnsure(
+				namespace,
+				labels.MustForName(componentLabels, OpenAPIName),
+				false,
+				apiDomain,
+				"/openapi/v2/swagger",
+				"",
+				httpUrl,
+				30000,
+				30000,
+				nil,
+			)
+			if err != nil {
+				return nil, err
+			}
+
 			queriers := []operator.QueryFunc{
 				operator.ResourceQueryToZitadelQuery(queryAdminR),
 				operator.ResourceQueryToZitadelQuery(queryMgmtRest),
@@ -216,6 +240,7 @@ func AdaptFunc(
 				operator.ResourceQueryToZitadelQuery(queryAuthorize),
 				operator.ResourceQueryToZitadelQuery(queryEndsession),
 				operator.ResourceQueryToZitadelQuery(queryIssuer),
+				operator.ResourceQueryToZitadelQuery(queryOpenAPI),
 			}
 
 			return operator.QueriersToEnsureFunc(internalMonitor, false, queriers, k8sClient, queried)

operator/zitadel/kinds/iam/zitadel/ambassador/http/adapt_test.go

@@ -233,6 +233,29 @@ func TestHttp_Adapt(t *testing.T) {
 	SetReturnResourceVersion(k8sClient, group, version, kind, namespace, AuthRName, "")
 	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, AuthRName, authR).MinTimes(1).MaxTimes(1)
 
+	openAPIName := labels.MustForName(componentLabels, OpenAPIName)
+	openAPI := &unstructured.Unstructured{
+		Object: map[string]interface{}{
+			"apiVersion": group + "/" + version,
+			"kind":       kind,
+			"metadata": map[string]interface{}{
+				"labels":    labels.MustK8sMap(openAPIName),
+				"name":      openAPIName.Name(),
+				"namespace": namespace,
+			},
+			"spec": map[string]interface{}{
+				"connect_timeout_ms": 30000,
+				"host":               ".",
+				"prefix":             "/openapi/v2/swagger",
+				"rewrite":            "",
+				"service":            url,
+				"timeout_ms":         30000,
+			},
+		},
+	}
+	SetReturnResourceVersion(k8sClient, group, version, kind, namespace, OpenAPIName, "")
+	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, OpenAPIName, openAPI).MinTimes(1).MaxTimes(1)
+
 	query, _, err := AdaptFunc(monitor, componentLabels, namespace, url, dns)
 	assert.NoError(t, err)
 	queried := map[string]interface{}{}
@@ -442,6 +465,29 @@ func TestHttp_Adapt2(t *testing.T) {
 	SetReturnResourceVersion(k8sClient, group, version, kind, namespace, AuthRName, "")
 	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, AuthRName, authR).MinTimes(1).MaxTimes(1)
 
+	openAPIName := labels.MustForName(componentLabels, OpenAPIName)
+	openAPI := &unstructured.Unstructured{
+		Object: map[string]interface{}{
+			"apiVersion": group + "/" + version,
+			"kind":       kind,
+			"metadata": map[string]interface{}{
+				"labels":    labels.MustK8sMap(openAPIName),
+				"name":      openAPIName.Name(),
+				"namespace": namespace,
+			},
+			"spec": map[string]interface{}{
+				"connect_timeout_ms": 30000,
+				"host":               "api.domain",
+				"prefix":             "/openapi/v2/swagger",
+				"rewrite":            "",
+				"service":            url,
+				"timeout_ms":         30000,
+			},
+		},
+	}
+	SetReturnResourceVersion(k8sClient, group, version, kind, namespace, OpenAPIName, "")
+	k8sClient.EXPECT().ApplyNamespacedCRDResource(group, version, kind, namespace, OpenAPIName, openAPI).MinTimes(1).MaxTimes(1)
+
 	query, _, err := AdaptFunc(monitor, componentLabels, namespace, url, dns)
 	assert.NoError(t, err)
 	queried := map[string]interface{}{}

proto/zitadel/app.proto

@@ -4,16 +4,29 @@ import "zitadel/object.proto";
 import "zitadel/message.proto";
 import "google/protobuf/duration.proto";
 import "validate/validate.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.app.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/app";
 
 message App {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    AppState state = 3;
+    AppState state = 3 [
-    string name = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the application";
+        }
+    ];
+    string name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Console\"";
+        }
+    ];
     oneof config {
         OIDCConfig oidc_config = 5;
         APIConfig api_config = 6;
@@ -35,28 +48,112 @@ message AppQuery {
 }
 
 message AppNameQuery {
-    string name = 1 [(validate.rules).string = {max_len: 200}];
+    string name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Conso\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message OIDCConfig {
-    repeated string redirect_uris = 1;
+    repeated string redirect_uris = 1 [
-    repeated OIDCResponseType response_types = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    repeated OIDCGrantType grant_types = 3;
+            example: "[\"console.zitadel.ch/authorized\"]";
-    OIDCAppType app_type = 4;
+            description: "Callback URI of the authorization request where the code or tokens will be sent to";
-    string client_id = 5;
+        }
-    string client_secret = 6;
+    ];
-    OIDCAuthMethodType auth_method_type = 7;
+    repeated OIDCResponseType response_types = 2 [
-    repeated string post_logout_redirect_uris = 8;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    OIDCVersion version = 9;
+            description: "Determines whether a code, id_token token or just id_token will be returned"
-    bool none_compliant = 10;
+        }
-    repeated zitadel.v1.LocalizedMessage compliance_problems = 11;
+    ];
-    bool dev_mode = 12;
+    repeated OIDCGrantType grant_types = 3 [
-    OIDCTokenType access_token_type = 13;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool access_token_role_assertion = 14;
+            description: "The flow type the application uses to gain access";
-    bool id_token_role_assertion = 15;
+        }
-    bool id_token_userinfo_assertion = 16;
+    ];
-    google.protobuf.Duration clock_skew = 17;
+    OIDCAppType app_type = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "determines the paradigm of the application";
+        }
+    ];
+    string client_id = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334@ZITADEL\"";
+            description: "generated oauth2/oidc client id";
+        }
+    ];
+    string client_secret = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for this config";
+        }
+    ];
+    OIDCAuthMethodType auth_method_type = 7 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines how the application passes login credentials";
+        }
+    ];
+    repeated string post_logout_redirect_uris = 8 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"console.zitadel.ch/logout\"]";
+            description: "ZITADEL will redirect to this link after a successful logout";
+        }
+    ];
+    OIDCVersion version = 9 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the oidc version used by the application";
+        }
+    ];
+    bool none_compliant = 10 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "specifies wheter the config is oidc compliant. A production configuration SHOULD be compliant";
+        }
+    ];
+    repeated zitadel.v1.LocalizedMessage compliance_problems = 11 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "lists the problems for non compliancy";
+        }
+    ];
+    bool dev_mode = 12 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "used for development";
+        }
+    ];
+    OIDCTokenType access_token_type = 13 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "type of the access token returned from ZITADEL";
+        }
+    ];
+    bool access_token_role_assertion = 14 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "adds roles to the claims of the access token (only if type == jwt) even if they are not requested by scopes";
+        }
+    ];
+    bool id_token_role_assertion = 15 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "adds roles to the claims of the id token even if they are not requested by scopes";
+        }
+    ];
+    bool id_token_userinfo_assertion = 16 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "claims of profile, email, address and phone scopes are added to the id token even if an access token is issued. Attention this violates the oidc specification";
+        }
+    ];
+    google.protobuf.Duration clock_skew = 17 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Used to compensate time difference of servers. Duration added to the \"exp\" claim and substracted from \"iat\", \"auth_time\" and \"nbf\" claims";
+            // min: "0s";
+            // max: "5s";
+        }
+    ];
 }
 
 enum OIDCResponseType {
@@ -99,7 +196,21 @@ enum APIAuthMethodType {
 }
 
 message APIConfig {
-    string client_id = 1;
+    string client_id = 1 [
-    string client_secret = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    APIAuthMethodType auth_method_type = 3;
+            example: "\"69629023906488334@ZITADEL\"";
+            description: "generated oauth2/oidc client_id";
+        }
+    ];
+    string client_secret = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for this config";
+        }
+    ];
+    APIAuthMethodType auth_method_type = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines how the api passes the login credentials";
+        }
+    ];
 }

proto/zitadel/auth.proto

@@ -416,7 +416,11 @@ message GetMyUserRequest {}
 
 message GetMyUserResponse {
     zitadel.user.v1.User user = 1;
-    google.protobuf.Timestamp last_login = 2;
+    google.protobuf.Timestamp last_login = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "The timestamp of the last successful login";
+        }
+    ];
 }
 
 message ListMyUserChangesRequest {
@@ -542,6 +546,7 @@ message RemoveMyPhoneResponse {
 }
 
 message ListMyLinkedIDPsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
     //PLANNED: queries for idp name and login name
 }
@@ -641,6 +646,7 @@ message RemoveMyPasswordlessResponse {
 }
 
 message ListMyUserGrantsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
 }
 
@@ -659,7 +665,9 @@ message UserGrant {
 }
 
 message ListMyProjectOrgsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //criterias the client is looking for
     repeated zitadel.org.v1.OrgQuery queries = 2;
 }
 

proto/zitadel/auth_n_key.proto

@@ -2,16 +2,30 @@ syntax = "proto3";
 
 import "zitadel/object.proto";
 import "google/protobuf/timestamp.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.authn.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/authn";
 
 message Key {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    KeyType type = 3;
+    KeyType type = 3 [
-    google.protobuf.Timestamp expiration_date = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the file type of the key";
+        }
+    ];
+    google.protobuf.Timestamp expiration_date = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the date a key will expire";
+            example: "\"3019-04-01T08:45:00.000000Z\"";
+        }
+    ];
 }
 
 enum KeyType {

proto/zitadel/change.proto

@@ -2,22 +2,61 @@ syntax = "proto3";
 
 import "google/protobuf/timestamp.proto";
 import "zitadel/message.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.change.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/change";
 
 message Change {
-    google.protobuf.Timestamp change_date = 1;
+    google.protobuf.Timestamp change_date = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the creation date of an event";
+            example: "\"2019-04-01T08:45:00.000000Z\"";
+        }
+    ];
     zitadel.v1.LocalizedMessage event_type = 2;
-    uint64 sequence = 3;
+    uint64 sequence = 3 [
-    string editor_id = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string editor_display_name = 5;
+            example: "\"2\"";
-    string resource_owner_id = 6;
+        }
+    ];
+    string editor_id = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the id of the user who created the event";
+            example: "\"69629023906488334\"";
+        }
+    ];
+    string editor_display_name = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the display name of the editor";
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
+    string resource_owner_id = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the organisation the event belongs to";
+            example: "\"69629023906488334\"";
+        }
+    ];
 }
 
 message ChangeQuery {
-    uint64 sequence = 1;
+    //sequence represents the order of events. It's always upcounting
-    uint32 limit = 2;
+    uint64 sequence = 1 [
-    bool asc = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2\"";
+        }
+    ];
+    uint32 limit = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "20";
+            description: "Maximum amount of events returned. Default is set to 1000 in https://github.com/caos/zitadel/blob/new-eventstore/cmd/zitadel/startup.yaml. If no limit is set or the limit exeeds the maximum configured ZITADEL will throw an error. If no limit is present the default is taken.";
+        }
+    ];
+    bool asc = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "default is descending"
+        }
+    ];
 }

proto/zitadel/idp.proto

@@ -2,36 +2,100 @@ syntax = "proto3";
 
 import "zitadel/object.proto";
 import "validate/validate.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.idp.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/idp";
 
 message IDP {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    IDPState state = 3;
+    IDPState state = 3 [
-    string name = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    IDPStylingType styling_type = 5;
+            description: "the state of the identity provider";
-    IDPOwnerType owner = 6;
+        }
+    ];
+    string name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"google\"";
+        }
+    ];
+    IDPStylingType styling_type = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "some identity providers specify the styling of the button to their login";
+        }
+    ];
+    IDPOwnerType owner = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the administrator of this identity provider";
+        }
+    ];
     oneof config {
         OIDCConfig oidc_config = 7;
     }
 }
 
 message IDPUserLink {
-    string user_id = 1;
+    string user_id = 1 [
-    string idp_id = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string idp_name = 3;
+            example: "\"69629023906488334\"";
-    string provided_user_id = 4;
+            description: "the id of the user"
-    string provided_user_name = 5;
+        }
-    IDPType idp_type = 6;
+    ];
+    string idp_id = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+            description: "the id of the identity provider";
+        }
+    ];
+    string idp_name = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"google\"";
+            description: "the name of the identity provider";
+        }
+    ];
+    string provided_user_id = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"as-12-df-89\"";
+            description: "the id of the user provided by the identity provider";
+        }
+    ];
+    string provided_user_name = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gigi.long-neck@gmail.com\"";
+            description: "the id of the identity provider";
+        }
+    ];
+    IDPType idp_type = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the authorization framework of the identity provider";
+        }
+    ];
 }
 
 message IDPLoginPolicyLink {
-    string idp_id = 1;
+    string idp_id = 1 [
-    string idp_name = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    IDPType idp_type = 3;
+            example: "\"69629023906488334\"";
+            description: "the id of the identity provider"
+        }
+    ];
+    string idp_name = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"google\"";
+            description: "the name of the identity provider"
+        }
+    ];
+    IDPType idp_type = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the authorization framework of the identity provider";
+        }
+    ];
 }
 
 enum IDPState {
@@ -45,24 +109,50 @@ enum IDPStylingType {
     STYLING_TYPE_GOOGLE = 1;
 }
 
+// authorization framework of the identity provider
 enum IDPType {
     IDP_TYPE_UNSPECIFIED = 0;
     IDP_TYPE_OIDC = 1;
     //PLANNED: IDP_TYPE_SAML
 }
 
+// the owner of the identity provider.
 enum IDPOwnerType {
     IDP_OWNER_TYPE_UNSPECIFIED = 0;
+    // system is managed by the ZITADEL administrators
     IDP_OWNER_TYPE_SYSTEM = 1;
+    // org is managed by de organisation administrators
     IDP_OWNER_TYPE_ORG = 2;
 }
 
 message OIDCConfig {
-    string client_id = 1;
+    string client_id = 1 [
-    string issuer = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    repeated string scopes = 3;
+            description: "client id generated by the identity provider";
-    OIDCMappingField display_name_mapping = 4;
+        }
-    OIDCMappingField username_mapping = 5;
+    ];
+    string issuer = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://accounts.google.com\"";
+            description: "the oidc issuer of the identity provider";
+        }
+    ];
+    repeated string scopes = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request on the identity provider";
+        }
+    ];
+    OIDCMappingField display_name_mapping = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "definition which field is mapped to the display name of the user";
+        }
+    ];
+    OIDCMappingField username_mapping = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "definition which field is mapped to the email of the user";
+        }
+    ];
 }
 
 enum OIDCMappingField {
@@ -72,16 +162,36 @@ enum OIDCMappingField {
 }
 
 message IDPIDQuery {
-    string id = 1 [(validate.rules).string = {max_len: 200}];
+    string id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
 }
 
 message IDPNameQuery {
-    string name = 1 [(validate.rules).string = {max_len: 200}];
+    string name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"google\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message IDPOwnerTypeQuery {
-    IDPOwnerType owner_type = 1 [(validate.rules).enum = {defined_only: true}];
+    IDPOwnerType owner_type = 1 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "search for custom or global identity providers";
+        }
+    ];
 }
 
 enum IDPFieldName {

proto/zitadel/management.proto

@@ -1857,8 +1857,11 @@ message GetUserByLoginNameGlobalResponse {
 }
 
 message ListUsersRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    // the field the result is sorted
     zitadel.user.v1.UserFieldName sorting_column = 2;
+    //criterias the client is looking for
     repeated zitadel.user.v1.SearchQuery queries = 3;
 }
 
@@ -1869,6 +1872,7 @@ message ListUsersResponse {
 }
 
 message ListUserChangesRequest {
+    //list limitations and ordering
     zitadel.change.v1.ChangeQuery query = 1;
     string user_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
 }
@@ -2196,6 +2200,7 @@ message GetMachineKeyByIDsResponse {
 
 message ListMachineKeysRequest {
     string user_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 2;
 }
 
@@ -2207,7 +2212,12 @@ message ListMachineKeysResponse {
 message AddMachineKeyRequest {
     string user_id = 1 [(validate.rules).string.min_len = 1];
     zitadel.authn.v1.KeyType type = 2 [(validate.rules).enum = {defined_only: true, not_in: [0]}];
-    google.protobuf.Timestamp expiration_date = 3;
+    google.protobuf.Timestamp expiration_date = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2519-04-01T08:45:00.000000Z\"";
+            description: "The date the key will expire and no logins will be possible";
+        }
+    ];
 }
 
 message AddMachineKeyResponse {
@@ -2227,6 +2237,7 @@ message RemoveMachineKeyResponse {
 
 message ListHumanLinkedIDPsRequest {
     string user_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 2;
 }
 
@@ -2246,8 +2257,11 @@ message RemoveHumanLinkedIDPResponse {
 }
 
 message ListUserMembershipsRequest {
+    //list limitations and ordering
     string user_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //the field the result is sorted
     zitadel.v1.ListQuery query = 2;
+    //criterias the client is looking for
     repeated zitadel.user.v1.MembershipQuery queries = 3;
 }
 
@@ -2267,6 +2281,7 @@ message GetOrgByDomainGlobalRequest {
 }
 
 message ListOrgChangesRequest {
+    //list limitations and ordering
     zitadel.change.v1.ChangeQuery query = 1;
 }
 
@@ -2301,7 +2316,9 @@ message ReactivateOrgResponse {
 }
 
 message ListOrgDomainsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //criterias the client is looking for
     repeated zitadel.org.v1.DomainSearchQuery queries = 2;
 }
 
@@ -2359,12 +2376,16 @@ message ListOrgMemberRolesResponse {
 }
 
 message ListOrgMembersRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //criterias the client is looking for
     repeated zitadel.member.v1.SearchQuery queries = 2;
 }
 
 message ListOrgMembersResponse {
+    //list limitations and ordering
     zitadel.v1.ListDetails details = 1;
+    //criterias the client is looking for
     repeated zitadel.member.v1.Member result = 2;
 }
 
@@ -2411,7 +2432,9 @@ message GetGrantedProjectByIDResponse {
 }
 
 message ListProjectsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //criterias the client is looking for
     repeated zitadel.project.v1.ProjectQuery queries = 2;
 }
 
@@ -2421,7 +2444,9 @@ message ListProjectsResponse {
 }
 
 message ListGrantedProjectsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //criterias the client is looking for
     repeated zitadel.project.v1.ProjectQuery queries = 2;
 }
 
@@ -2431,6 +2456,7 @@ message ListGrantedProjectsResponse {
 }
 
 message ListProjectChangesRequest {
+    //list limitations and ordering
     zitadel.change.v1.ChangeQuery query = 1;
     string project_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
 }
@@ -2541,7 +2567,9 @@ message RemoveProjectRoleResponse {
 
 message ListProjectRolesRequest {
     string project_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 2;
+    //criterias the client is looking for
     repeated zitadel.project.v1.RoleQuery queries = 3;
 }
 
@@ -2552,7 +2580,9 @@ message ListProjectRolesResponse {
 
 message ListProjectMembersRequest {
     string project_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 2;
+    //criterias the client is looking for
     repeated zitadel.member.v1.SearchQuery queries = 3;
 }
 
@@ -2601,7 +2631,9 @@ message GetAppByIDResponse {
 
 message ListAppsRequest {
     string project_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 2;
+    //criterias the client is looking for
     repeated zitadel.app.v1.AppQuery queries = 3;
 }
 
@@ -2611,6 +2643,7 @@ message ListAppsResponse {
 }
 
 message ListAppChangesRequest {
+    //list limitations and ordering
     zitadel.change.v1.ChangeQuery query = 1;
     string project_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
     string app_id = 3 [(validate.rules).string = {min_len: 1, max_len: 200}];
@@ -2642,8 +2675,18 @@ message AddOIDCAppRequest {
 message AddOIDCAppResponse {
     string app_id = 1;
     zitadel.v1.ObjectDetails details = 2;
-    string client_id = 3;
+    string client_id = 3 [
-    string client_secret = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for this config";
+        }
+    ];
+    string client_secret = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for this config";
+        }
+    ];
     bool none_compliant = 5;
     repeated zitadel.v1.LocalizedMessage compliance_problems = 6;
 }
@@ -2657,8 +2700,18 @@ message AddAPIAppRequest {
 message AddAPIAppResponse {
     string app_id = 1;
     zitadel.v1.ObjectDetails details = 2;
-    string client_id = 3;
+    string client_id = 3 [
-    string client_secret = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for this config";
+        }
+    ];
+    string client_secret = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for this config";
+        }
+    ];
 }
 
 message UpdateAppRequest {
@@ -2736,7 +2789,12 @@ message RegenerateOIDCClientSecretRequest {
 }
 
 message RegenerateOIDCClientSecretResponse {
-    string client_secret = 1;
+    string client_secret = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gjöq34589uasgh\"";
+            description: "generated secret for the client";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
 }
 
@@ -2761,6 +2819,7 @@ message GetAppKeyResponse {
 }
 
 message ListAppKeysRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
     string app_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
     string project_id = 3 [(validate.rules).string = {min_len: 1, max_len: 200}];
@@ -2774,7 +2833,12 @@ message AddAppKeyRequest {
     string project_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
     string app_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
     zitadel.authn.v1.KeyType type = 3 [(validate.rules).enum = {defined_only: true, not_in: [0]}];
-    google.protobuf.Timestamp expiration_date = 4;
+    google.protobuf.Timestamp expiration_date = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2519-04-01T08:45:00.000000Z\"";
+            description: "The date the key will expire and no logins will be possible";
+        }
+    ];
 }
 
 message AddAppKeyResponse {
@@ -2804,7 +2868,9 @@ message GetProjectGrantByIDResponse {
 
 message ListProjectGrantsRequest {
     string project_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 2;
+    //criterias the client is looking for
     repeated zitadel.project.v1.ProjectGrantQuery queries = 3;
 }
 
@@ -2872,7 +2938,9 @@ message ListProjectGrantMemberRolesResponse {
 message ListProjectGrantMembersRequest {
     string project_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
     string grant_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 3;
+    //criterias the client is looking for
     repeated zitadel.member.v1.SearchQuery queries = 4;
 }
 
@@ -2923,7 +2991,9 @@ message GetUserGrantByIDResponse {
 }
 
 message ListUserGrantRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //criterias the client is looking for
     repeated zitadel.user.v1.UserGrantQuery queries = 2;
 }
 
@@ -3246,7 +3316,11 @@ message GetDefaultLabelPolicyResponse {
 message AddCustomLabelPolicyRequest {
     string primary_color = 1 [(validate.rules).string = {min_len: 1, max_len: 50}];
     string secondary_color = 2 [(validate.rules).string = {min_len: 1, max_len: 50}];
-    bool hide_login_name_suffix = 3;
+    bool hide_login_name_suffix = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.ch/architecture#Reserved_Scopes";
+        }
+    ];
 }
 
 message AddCustomLabelPolicyResponse {
@@ -3256,7 +3330,11 @@ message AddCustomLabelPolicyResponse {
 message UpdateCustomLabelPolicyRequest {
     string primary_color = 1 [(validate.rules).string = {min_len: 1, max_len: 50}];
     string secondary_color = 2 [(validate.rules).string = {min_len: 1, max_len: 50}];
-    bool hide_login_name_suffix = 3;
+    bool hide_login_name_suffix = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.ch/architecture#Reserved_Scopes";
+        }
+    ];
 }
 
 message UpdateCustomLabelPolicyResponse {
@@ -3278,8 +3356,11 @@ message GetOrgIDPByIDResponse {
 }
 
 message ListOrgIDPsRequest {
+    //list limitations and ordering
     zitadel.v1.ListQuery query = 1;
+    //the field the result is sorted
     zitadel.idp.v1.IDPFieldName sorting_column = 2;
+    //criterias the client is looking for
     repeated IDPQuery queries = 3;
 }
 
@@ -3300,15 +3381,56 @@ message ListOrgIDPsResponse {
 }
 
 message AddOrgOIDCIDPRequest {
-    string name = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    string name = 1 [
-    zitadel.idp.v1.IDPStylingType styling_type = 2 [(validate.rules).enum = {defined_only: true}];
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"google\"";
+        }
+    ];
+    zitadel.idp.v1.IDPStylingType styling_type = 2 [
+        (validate.rules).enum = {defined_only: true},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "some identity providers specify the styling of the button to their login";
+        }
+    ];
 
-    string client_id = 3 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    string client_id = 3 [
-    string client_secret = 4 [(validate.rules).string = {min_len: 1, max_len: 200}];
+        (validate.rules).string = {min_len: 1, max_len: 200},
-    string issuer = 5 [(validate.rules).string = {min_len: 1, max_len: 200}];
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    repeated string scopes = 6;
+            description: "client id generated by the identity provider";
-    zitadel.idp.v1.OIDCMappingField display_name_mapping = 7 [(validate.rules).enum = {defined_only: true}];
+        }
-    zitadel.idp.v1.OIDCMappingField username_mapping = 8 [(validate.rules).enum = {defined_only: true}];
+    ];
+    string client_secret = 4 [
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "client secret generated by the identity provider";
+        }
+    ];
+    string issuer = 5 [
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://accounts.google.com\"";
+            description: "the oidc issuer of the identity provider";
+        }
+    ];
+    repeated string scopes = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request on the identity provider";
+        }
+    ];
+    zitadel.idp.v1.OIDCMappingField display_name_mapping = 7 [
+        (validate.rules).enum = {defined_only: true},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "definition which field is mapped to the display name of the user";
+        }
+    ];
+    zitadel.idp.v1.OIDCMappingField username_mapping = 8 [
+        (validate.rules).enum = {defined_only: true},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "definition which field is mapped to the email of the user";
+        }
+    ];
 }
 
 message AddOrgOIDCIDPResponse {
@@ -3340,8 +3462,18 @@ message RemoveOrgIDPResponse {}
 
 message UpdateOrgIDPRequest {
     string idp_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
-    string name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    string name = 2 [
-    zitadel.idp.v1.IDPStylingType styling_type = 3 [(validate.rules).enum = {defined_only: true}];
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"google\"";
+        }
+    ];
+    zitadel.idp.v1.IDPStylingType styling_type = 3 [
+        (validate.rules).enum = {defined_only: true},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "some identity providers specify the styling of the button to their login";
+        }
+    ];
 }
 
 message UpdateOrgIDPResponse {
@@ -3349,14 +3481,50 @@ message UpdateOrgIDPResponse {
 }
 
 message UpdateOrgIDPOIDCConfigRequest {
-    string idp_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    string idp_id = 1 [
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
 
-    string client_id = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
+    string client_id = 2 [
-    string client_secret = 3 [(validate.rules).string = {max_len: 200}];
+        (validate.rules).string = {min_len: 1, max_len: 200},
-    string issuer = 4 [(validate.rules).string = {min_len: 1, max_len: 200}];
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    repeated string scopes = 5;
+            description: "client id generated by the identity provider";
-    zitadel.idp.v1.OIDCMappingField display_name_mapping = 6 [(validate.rules).enum = {defined_only: true}];
+        }
-    zitadel.idp.v1.OIDCMappingField username_mapping = 7 [(validate.rules).enum = {defined_only: true}];
+    ];
+    string client_secret = 3 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "client secret generated by the identity provider. If empty the secret is not overwritten";
+        }
+    ];
+    string issuer = 4 [
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://accounts.google.com\"";
+            description: "the oidc issuer of the identity provider";
+        }
+    ];
+    repeated string scopes = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request on the identity provider";
+        }
+    ];
+    zitadel.idp.v1.OIDCMappingField display_name_mapping = 6 [
+        (validate.rules).enum = {defined_only: true},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "definition which field is mapped to the display name of the user";
+        }
+    ];
+    zitadel.idp.v1.OIDCMappingField username_mapping = 7 [
+        (validate.rules).enum = {defined_only: true},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "definition which field is mapped to the email of the user";
+        }
+    ];
 }
 
 message UpdateOrgIDPOIDCConfigResponse {

proto/zitadel/member.proto

@@ -2,20 +2,55 @@ syntax = "proto3";
 
 import "zitadel/object.proto";
 import "validate/validate.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.member.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/member";
 
 message Member {
-    string user_id = 1;
+    string user_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    repeated string roles = 3;
+    repeated string roles = 3 [
-    string preferred_login_name = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string email = 5;
+            example: "[\"role.super.man\"]";
-    string first_name = 6;
+            description: "the role keys granted to the user"
-    string last_name = 7;
+        }
-    string display_name = 8;
+    ];
+    string preferred_login_name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gigi@caos.ch\"";
+            description: "preferred login name of the user"
+        }
+    ];
+    string email = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gigi@caos.ch\"";
+            description: "preferred login name of the user"
+        }
+    ];
+    string first_name = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Gigi\"";
+            description: "first name of the user"
+        }
+    ];
+    string last_name = 7 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Giraffe\"";
+            description: "last name of the user"
+        }
+    ];
+    string display_name = 8 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "display name of the user"
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
 }
 
 message SearchQuery {
@@ -30,20 +65,61 @@ message SearchQuery {
 }
 
 message FirstNameQuery {
-    string first_name = 1 [(validate.rules).string = {max_len: 200}];
+    string first_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"Gigi\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message LastNameQuery {
-    string last_name = 1 [(validate.rules).string = {max_len: 200}];
+    string last_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"Giraffe\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message EmailQuery {
-    string email = 1 [(validate.rules).string = {max_len: 200}];
+    string email = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)"
+            max_length: 200;
+            example: "\"gigi@caos.ch\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message UserIDQuery {
-    string user_id = 1 [(validate.rules).string = {max_len: 200}];
+    string user_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the id of the user"
+            max_length: 200;
+            example: "\"69629023906488334\"";
+        }
+    ];
 }

proto/zitadel/object.proto

@@ -1,6 +1,7 @@
 syntax = "proto3";
 
 import "google/protobuf/timestamp.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.v1;
 
@@ -12,7 +13,11 @@ message ObjectDetails {
     // on read: the sequence of the last event reduced by the projection
     //
     // on manipulation: the timestamp of the event(s) added by the manipulation
-    uint64 sequence = 1;
+    uint64 sequence = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2\"";
+        }
+    ];
     //creation_date is the timestamp where the first operation on the object was made
     //
     // on read: the timestamp of the first event of the object
@@ -26,19 +31,48 @@ message ObjectDetails {
     // on manipulation: the
     google.protobuf.Timestamp change_date = 3;
     //resource_owner is the organisation an object belongs to
-    string resource_owner = 4;
+    string resource_owner = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
 }
 
 message ListQuery {
-    uint64 offset = 1;
+    uint64 offset = 1 [
-    uint32 limit = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool asc = 3;
+            example: "\"10\"";
+        }
+    ];
+    uint32 limit = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "20";
+            description: "Maximum amount of events returned. Default is set to 1000 in https://github.com/caos/zitadel/blob/new-eventstore/cmd/zitadel/startup.yaml. If limit exeeds the maximum configured ZITADEL will throw an error. If no limit is present the default is taken.";
+        }
+    ];
+    bool asc = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "default is descending"
+        }
+    ];
 }
 
 message ListDetails {
-    uint64 total_result = 1;
+    uint64 total_result = 1 [
-    uint64 processed_sequence = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    google.protobuf.Timestamp view_timestamp = 3;
+            example: "\"2\"";
+        }
+    ];
+    uint64 processed_sequence = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"267831\"";
+        }
+    ];
+    google.protobuf.Timestamp view_timestamp = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the last time the view got updated"
+        }
+    ];
 }
 
 enum TextQueryMethod {

proto/zitadel/org.proto

@@ -2,17 +2,34 @@ syntax = "proto3";
 
 import "zitadel/object.proto";
 import "validate/validate.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.org.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/org";
 
 message Org {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    OrgState state = 3;
+    OrgState state = 3 [
-    string name = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string primary_domain = 5;
+            description: "current state of the organisation";
+        }
+    ];
+    string name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"CAOS AG\"";
+        }
+    ];
+    string primary_domain = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"caos.ch\"";
+        }
+    ];
 }
 
 enum OrgState {
@@ -22,12 +39,32 @@ enum OrgState {
 }
 
 message Domain {
-    string org_id = 1;
+    string org_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    string domain_name = 3;
+    string domain_name = 3 [
-    bool is_verified = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool is_primary = 5;
+            example: "\"caos.ch\"";
-    DomainValidationType validation_type = 6;
+        }
+    ];
+    bool is_verified = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the domain is verified"
+        }
+    ];
+    bool is_primary = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the domain is the primary domain"
+        }
+    ];
+    DomainValidationType validation_type = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines the protocol the domain was validated with";
+        }
+    ];
 }
 
 enum DomainValidationType {
@@ -46,13 +83,33 @@ message OrgQuery {
 }
 
 message OrgNameQuery {
-    string name = 1 [(validate.rules).string = {max_len: 200}];
+    string name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"caos ag\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message OrgDomainQuery {
-    string domain = 1 [(validate.rules).string = {max_len: 200}];
+    string domain = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"CAOS.C\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 enum OrgFieldName {
@@ -69,6 +126,16 @@ message DomainSearchQuery {
 }
 
 message DomainNameQuery {
-    string name = 1 [(validate.rules).string = {max_len: 200}];
+    string name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"caos.ch\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }

proto/zitadel/policy.proto

@@ -1,6 +1,7 @@
 syntax = "proto3";
 
 import "zitadel/object.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.policy.v1;
 
@@ -8,26 +9,74 @@ option go_package ="github.com/caos/zitadel/pkg/grpc/policy";
 
 message OrgIAMPolicy {
     zitadel.v1.ObjectDetails details = 1;
-    bool user_login_must_be_domain = 2;
+    bool user_login_must_be_domain = 2 [
-    bool is_default = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the username has to end with the domain of it's organisation"
+        }
+    ];
+    bool is_default = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the organisation's admin changed the policy"
+        }
+    ];
 }
 
 message LabelPolicy {
     zitadel.v1.ObjectDetails details = 1;
-    string primary_color = 2;
+    string primary_color = 2 [
-    string secondary_color = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool is_default = 4;
+            description: "hex value for primary color"
-    bool hide_login_name_suffix = 5;
+        }
+    ];
+    string secondary_color = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for secondary color"
+        }
+    ];
+    bool is_default = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the organisation's admin changed the policy"
+        }
+    ];
+    bool hide_login_name_suffix = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.ch/architecture#Reserved_Scopes";
+        }
+    ];
 }
 
 message LoginPolicy {
     zitadel.v1.ObjectDetails details = 1;
-    bool allow_username_password = 2;
+    bool allow_username_password = 2 [
-    bool allow_register = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool allow_external_idp = 4;
+            description: "defines if a user is allowed to login with his username and password"
-    bool force_mfa = 5;
+        }
-    PasswordlessType passwordless_type = 6;
+    ];
-    bool is_default = 7;
+    bool allow_register = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if a person is allowed to register a user on this organisation"
+        }
+    ];
+    bool allow_external_idp = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if a user is allowed to add a defined identity provider. E.g. Google auth"
+        }
+    ];
+    bool force_mfa = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if a user MUST use a multi factor to log in"
+        }
+    ];
+    PasswordlessType passwordless_type = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if passwordless is allowed for users"
+        }
+    ];
+    bool is_default = 7 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the organisation's admin changed the policy"
+        }
+    ];
 }
 
 enum SecondFactorType {
@@ -49,24 +98,75 @@ enum PasswordlessType {
 
 message PasswordComplexityPolicy {
     zitadel.v1.ObjectDetails details = 1;
-    uint64 min_length = 2;
+    uint64 min_length = 2 [
-    bool has_uppercase = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool has_lowercase = 4;
+            example: "\"8\""
-    bool has_number = 5;
+        }
-    bool has_symbol = 6;
+    ];
-    bool is_default = 7;
+    bool has_uppercase = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the password MUST contain an upper case letter"
+        }
+    ];
+    bool has_lowercase = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the password MUST contain a lower case letter"
+        }
+    ];
+    bool has_number = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the password MUST contain a number"
+        }
+    ];
+    bool has_symbol = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the password MUST contain a symbol. E.g. \"$\""
+        }
+    ];
+    bool is_default = 7 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the organisation's admin changed the policy"
+        }
+    ];
 }
 
 message PasswordAgePolicy {
     zitadel.v1.ObjectDetails details = 1;
-    uint64 max_age_days = 2;
+    uint64 max_age_days = 2 [
-    uint64 expire_warn_days = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool is_default = 4;
+            description: "Maximum days since last password change"
+            example: "\"365\""
+        }
+    ];
+    uint64 expire_warn_days = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Days before the password expiry the user gets notified to change the password"
+            example: "\"10\""
+        }
+    ];
+    bool is_default = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the organisation's admin changed the policy"
+        }
+    ];
 }
 
 message PasswordLockoutPolicy {
     zitadel.v1.ObjectDetails details = 1;
-    uint64 max_attempts = 2;
+    uint64 max_attempts = 2 [
-    bool show_lockout_failure = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    bool is_default = 4;
+            description: "Maximum attempts before the account gets locked. Attempts are reset as soon as the password is entered correct or the password is reset."
+            example: "\"10\""
+        }
+    ];
+    bool show_lockout_failure = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Enables if the failure should be shown to de user, sometimes for security issues the user should not get to much information"
+        }
+    ];
+    bool is_default = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines if the organisation's admin changed the policy"
+        }
+    ];
 }

proto/zitadel/project.proto

@@ -2,16 +2,29 @@ syntax = "proto3";
 
 import "zitadel/object.proto";
 import "validate/validate.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 
 package zitadel.project.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/project";
 
 message Project {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    string name = 3;
+    string name = 3 [
-    ProjectState state = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ZITADEL\""
+        }
+    ];
+    ProjectState state = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the project";
+        }
+    ];
     // describes if roles of user should be added in token
     bool project_role_assertion = 5;
     // ZITADEL checks if the user has at least one on this project
@@ -19,16 +32,52 @@ message Project {
 }
 
 message GrantedProject {
-    string grant_id = 1;
+    string grant_id = 1 [
-    string granted_org_id = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string granted_org_name = 3;
+            example: "\"69629023906488334\""
-    repeated string granted_role_keys = 4;
+        }
-    ProjectGrantState state = 5;
+    ];
+    string granted_org_id = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    string granted_org_name = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Some Organisation\""
+        }
+    ];
+    repeated string granted_role_keys = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"role.super.man\"]"
+        }
+    ];
+    ProjectGrantState state = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the project grant";
+        }
+    ];
     
-    string project_id = 6;
+    string project_id = 6 [
-    string project_name = 7;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string project_owner_id = 8;
+            example: "\"69629023906488334\""
-    string project_owner_name = 9;
+        }
+    ];
+    string project_name = 7 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ZITADEL\""
+        }
+    ];
+    string project_owner_id = 8 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    string project_owner_name = 9 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"CAOS AG\""
+        }
+    ];
 
     zitadel.v1.ObjectDetails details = 10;
 }
@@ -54,15 +103,37 @@ message ProjectQuery {
 }
 
 message ProjectNameQuery {
-    string name = 1 [(validate.rules).string = {max_len: 200}];
+    string name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ZITADEL\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message Role {
-    string key = 1;
+    string key = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"role.super.man\""
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    string display_name = 3;
+    string display_name = 3 [
-    string group = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Super man\""
+        }
+    ];
+    string group = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"people\""
+        }
+    ];
 }
 
 message RoleQuery {
@@ -75,13 +146,33 @@ message RoleQuery {
 }
 
 message RoleKeyQuery {
-    string key = 1 [(validate.rules).string = {max_len: 200}];
+    string key = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"role.super.man\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message RoleDisplayNameQuery {
-    string display_name = 1 [(validate.rules).string = {max_len: 200}];
+    string display_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"SUPER\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message ProjectGrantQuery {
@@ -94,11 +185,31 @@ message ProjectGrantQuery {
 }
 
 message GrantProjectNameQuery {
-    string name = 1 [(validate.rules).string = {max_len: 200}];
+    string name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ZITADEL\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message GrantRoleKeyQuery {
-    string role_key = 1 [(validate.rules).string = {max_len: 200}];
+    string role_key = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"role.super.man\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }

proto/zitadel/user.proto

@@ -3,20 +3,50 @@ syntax = "proto3";
 import "zitadel/object.proto";
 import "validate/validate.proto";
 
+import "protoc-gen-openapiv2/options/annotations.proto";
+
 package zitadel.user.v1;
 
 option go_package ="github.com/caos/zitadel/pkg/grpc/user";
 
 message User {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    UserState state = 3;
+    UserState state = 3 [
-    string user_name = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    repeated string login_names = 5;
+            description: "current state of the user";
-    string preferred_login_name = 6;
+        }
+    ];
+    string user_name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"mr_long_neck\"";
+        }
+    ];
+    repeated string login_names = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"gigi@caos.ch\", \"gigi@caos-ag.zitadel.ch\"]";
+        }
+    ];
+    string preferred_login_name = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gigi@caos.ch\"";
+        }
+    ];
     oneof type {
-        Human human = 7;
+        Human human = 7 [
-        Machine machine = 8;
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use human or machine"
+            }
+        ];
+        Machine machine = 8 [
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use human or machine"
+            }
+        ];
     }
 }
 
@@ -34,39 +64,82 @@ message Human {
     Profile profile = 1;
     Email email = 2;
     Phone phone = 3;
-    Address address = 4;
 }
 
 message Machine {
-    string name = 1;
+    string name = 1 [
-    string description = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"zitadel\"";
+        }
+    ];
+    string description = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"The one and only IAM\"";
+        }
+    ];
 }
 
 message Profile {
-    string first_name = 1;
+    string first_name = 1 [
-    string last_name = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string nick_name = 3;
+            example: "\"Gigi\"";
-    string display_name = 4;
+        }
-    string preferred_language = 5;
+    ];
-    Gender gender = 6;
+    string last_name = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Giraffe\"";
+        }
+    ];
+    string nick_name = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"long_neck\"";
+        }
+    ];
+    string display_name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "a user can set his display name, if nothing is set ZITADEL computes \"first_name last_name\""
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
+    string preferred_language = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "language tag analog https://tools.ietf.org/html/rfc3066"
+            example: "\"en\"";
+        }
+    ];
+    Gender gender = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the gender of the human";
+        }
+    ];
 }
 
 message Email {
-    string email = 1;
+    string email = 1 [
-    bool is_email_verified = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)"
+            example: "\"gigi@caos.ch\"";
+        }
+    ];
+    bool is_email_verified = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Is true if the user verified his email or if the email is managed outside ZITADEL"
+        }
+    ];
 }
 
 message Phone {
-    string phone = 1;
+    string phone = 1 [
-    bool is_phone_verified = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-}
+            description: "mobile phone number of the user. (use global pattern of spec https://tools.ietf.org/html/rfc3966)"
-
+            example: "\"+41 71 000 00 00\"";
-message Address {
+        }
-    string country = 1;
+    ];
-    string locality = 2;
+    bool is_phone_verified = 2 [
-    string postal_code = 3;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string region = 4;
+            description: "Is true if the user verified his phone or if the phone is managed outside ZITADEL"
-    string street_address = 5;
+        }
+    ];
 }
 
 enum Gender {
@@ -92,43 +165,114 @@ message SearchQuery {
 }
 
 message UserNameQuery {
-    string user_name = 1 [(validate.rules).string = {max_len: 200}];
+    string user_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"mr_long_neck\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message FirstNameQuery {
-    string first_name = 1 [(validate.rules).string = {max_len: 200}];
+    string first_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"Gigi\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message LastNameQuery {
-    string last_name = 1 [(validate.rules).string = {max_len: 200}];
+    string last_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"Giraffe\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message NickNameQuery {
     string nick_name = 1 [(validate.rules).string = {max_len: 200}];
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message DisplayNameQuery {
-    string display_name = 1 [(validate.rules).string = {max_len: 200}];
+    string display_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 message EmailQuery {
-    string email_address = 1 [(validate.rules).string = {max_len: 200}];
+    string email_address = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)"
+            max_length: 200;
+            example: "\"gigi@caos.ch\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used";
+        }
+    ];
 }
 
 //UserStateQuery is always equals
 message StateQuery {
-    UserState state = 1 [(validate.rules).enum.defined_only = true];
+    UserState state = 1 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the user";
+        }
+    ];
 }
 
 //UserTypeQuery is always equals
 message TypeQuery {
-    Type type = 1 [(validate.rules).enum.defined_only = true];
+    Type type = 1 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the type of the user";
+        }
+    ];
 }
 
 enum Type {
@@ -150,10 +294,22 @@ enum UserFieldName {
 }
 
 message AuthFactor {
-    AuthFactorState state = 1;
+    AuthFactorState state = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the auth factor";
+        }
+    ];
     oneof type {
-        AuthFactorOTP otp = 2;
+        AuthFactorOTP otp = 2 [
-        AuthFactorU2F u2f = 3;
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use otp or u2f"
+            }
+        ];
+        AuthFactorU2F u2f = 3 [
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use otp or u2f"
+            }
+        ];
     }
 }
 
@@ -167,35 +323,105 @@ enum AuthFactorState {
 message AuthFactorOTP {}
 
 message AuthFactorU2F {
-    string id = 1;
+    string id = 1 [
-    string name = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    string name = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"fido key\""
+        }
+    ];
 }
 
 message WebAuthNKey {
-    bytes public_key = 1;
+    bytes public_key = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "json representation of public key credential creation options used by the webauthn client"
+        }
+    ];
 }
 
 message WebAuthNVerification {
-    bytes public_key_credential = 1 [(validate.rules).bytes.min_len = 50]; //TODO: define correct min and max len
+    bytes public_key_credential = 1 [
-    string token_name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
+        (validate.rules).bytes.min_len = 55,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "json representation of public key credential issued by the webauthn client";
+            min_length: 55;
+            max_length: 1048576; //1 mb
+            //TODO: add example validate max
+        }
+    ];
+    string token_name = 2 [
+        (validate.rules).string = {min_len: 1, max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            min_length: 1;
+            max_length: 200;
+            example: "\"fido key\""
+        }
+    ];
 }
 
 message WebAuthNToken {
-    string id = 1;
+    string id = 1 [
-    AuthFactorState state = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string name = 3;
+            example: "\"69629023906488334\""
+        }
+    ];
+    AuthFactorState state = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the token";
+        }
+    ];
+    string name = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            min_length: 1;
+            max_length: 200;
+            example: "\"fido key\""
+        }
+    ];
 }
 
 message Membership {
-    string user_id = 1;
+    string user_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    repeated string roles = 3;
+    repeated string roles = 3 [
-    string display_name = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"IAM_OWNER\"]"
+        }
+    ];
+    string display_name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "display name of the user"
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
     oneof type {
-        bool iam = 5;
+        bool iam = 5 [
-        string org_id = 6;
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        string project_id = 7;
+                description: "one of type use iam, org id, project id or project grant id"
-        string project_grant_id = 8;
+            }
+        ];
+        string org_id = 6 [
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use iam, org id, project id or project grant id"
+            }
+        ];
+        string project_id = 7 [
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use iam, org id, project id or project grant id"
+            }
+        ];
+        string project_grant_id = 8 [
+            (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+                description: "one of type use iam, org id, project id or project grant id"
+            }
+        ];
     }
 }
 
@@ -210,30 +436,78 @@ message MembershipQuery {
     }
 }
 
+// this query is always equals
 message MembershipOrgQuery {
-    string org_id = 1 [(validate.rules).string = {max_len: 200}];
+    string org_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
+// this query is always equals
 message MembershipProjectQuery {
-    string project_id = 1 [(validate.rules).string = {max_len: 200}];
+    string project_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
+// this query is always equals
 message MembershipProjectGrantQuery {
-    string project_grant_id = 1 [(validate.rules).string = {max_len: 200}];
+    string project_grant_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
+// this query is always equals
 message MembershipIAMQuery {
     bool iam = 1;
 }
 
 message Session {
-    string session_id = 1;
+    string session_id = 1 [
-    string agent_id = 2;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    SessionState auth_state = 3;
+            example: "\"69629023906488334\""
-    string user_id = 4;
+        }
-    string user_name = 5;
+    ];
-    string login_name = 7;
+    string agent_id = 2 [
-    string display_name = 8;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    SessionState auth_state = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the session";
+        }
+    ];
+    string user_id = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    string user_name = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"mr_long_neck\"";
+        }
+    ];
+    string login_name = 7 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gigi@caos.ch\"";
+        }
+    ];
+    string display_name = 8 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "the display name of the user"
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 9;
 }
 
@@ -244,25 +518,87 @@ enum SessionState {
 }
 
 message UserGrant {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
-    repeated string role_keys = 3;
+    repeated string role_keys = 3 [
-    UserGrantState state = 4;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"role.super.man\"]"
+        }
+    ];
+    UserGrantState state = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the user";
+        }
+    ];
     
-    string user_id = 5;
+    string user_id = 5 [
-    string user_name = 6;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string first_name = 7;
+            example: "\"69629023906488334\""
-    string last_name = 8;
+        }
-    string email = 9;
+    ];
-    string display_name = 10;
+    string user_name = 6 [
-    
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string org_id = 11;
+            example: "\"mr_long_neck\"";
-    string org_name = 12;
+        }
-    string org_domain = 13;
+    ];
-    
+    string first_name = 7 [
-    string project_id = 14;
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string project_name = 15;
+            example: "\"Gigi\"";
-    string project_grant_id = 16;
+        }
+    ];
+    string last_name = 8 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Giraffe\"";
+        }
+    ];
+    string email = 9 [
+        (validate.rules).string.email = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)"
+            example: "\"gigi@caos.ch\"";
+        }
+    ];
+    string display_name = 10 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "display name of the user"
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
+    string org_id = 11 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    string org_name = 12 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"CAOS AG\"";
+        }
+    ];
+    string org_domain = 13 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"caos.ch\"";
+        }
+    ];
+    string project_id = 14 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+    string project_name = 15 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ZITADEL\"";
+        }
+    ];
+    string project_grant_id = 16 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
 enum UserGrantState {
@@ -292,11 +628,21 @@ message UserGrantQuery {
 }
 
 message UserGrantProjectIDQuery {
-    string project_id = 1 [(validate.rules).string = {max_len: 200}];
+    string project_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
 message UserGrantUserIDQuery {
-    string user_id = 1 [(validate.rules).string = {max_len: 200}];
+    string user_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
 message UserGrantWithGrantedQuery {
@@ -304,53 +650,147 @@ message UserGrantWithGrantedQuery {
 }
 
 message UserGrantRoleKeyQuery {
-    string role_key = 1 [(validate.rules).string = {max_len: 200}];
+    string role_key = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"role.super.man\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantProjectGrantIDQuery {
-    string project_grant_id = 1 [(validate.rules).string = {max_len: 200}];
+    string project_grant_id = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
 }
 
 message UserGrantUserNameQuery {
-    string user_name = 1 [(validate.rules).string = {max_len: 200}];
+    string user_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"mr_long_neck\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantFirstNameQuery {
-    string first_name = 1 [(validate.rules).string = {max_len: 200}];
+    string first_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Gigi\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantLastNameQuery {
-    string last_name = 1 [(validate.rules).string = {max_len: 200}];
+    string last_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Giraffe\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantEmailQuery {
-    string email = 1 [(validate.rules).string = {max_len: 200}];
+    string email = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"gigi@caos.ch\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantOrgNameQuery {
-    string org_name = 1 [(validate.rules).string = {max_len: 200}];
+    string org_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"cao\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantOrgDomainQuery {
-    string org_domain = 1 [(validate.rules).string = {max_len: 200}];
+    string org_domain = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"OS AG\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which text equality method is used"
+        }
+    ];
 }
 
 message UserGrantProjectNameQuery {
-    string project_name = 1 [(validate.rules).string = {max_len: 200}];
+    string project_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ITADE\""
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "3"
+        }
+    ];
 }
 
-//TODO: needed as you can search first and last name?
 message UserGrantDisplayNameQuery {
-    string display_name = 1;
+    string display_name = 1 [
-    zitadel.v1.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "display name of a user"
+            example: "\"Gigi Giraffe\"";
+        }
+    ];
+    zitadel.v1.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "defines which equality method is used";
+        }
+    ];
 }
 
 //PLANNED: login name query