docs: improve enum handling and completeness (#3714)

.schema/openapi/patches/identity.yaml

@@ -1,26 +1,3 @@
-- op: add
-  path: /components/schemas/identityState/enum
-  value:
-    - active
-    - inactive
-- op: add
-  path: /components/schemas/identityCredentialsType/enum
-  value:
-    - password
-    - totp
-    - oidc
-    - webauthn
-    - lookup_secret
-    - code
-- op: add
-  path: /paths/~1admin~1identities~1{id}/get/parameters/1/schema/items/enum
-  value:
-    - password
-    - totp
-    - oidc
-    - webauthn
-    - lookup_secret
-    - code
 - op: remove
   path: /components/schemas/updateIdentityBody/properties/metadata_admin/type
 - op: remove

identity/credentials.go

@@ -75,9 +75,19 @@ func (n NullableAuthenticatorAssuranceLevel) ToAAL() (AuthenticatorAssuranceLeve
 // CredentialsType  represents several different credential types, like password credentials, passwordless credentials,
 // and so on.
 //
-// swagger:model identityCredentialsType
+// swagger:enum CredentialsType
 type CredentialsType string
 
+// Please make sure to add all of these values to the test that ensures they are created during migration
+const (
+	CredentialsTypePassword CredentialsType = "password"
+	CredentialsTypeOIDC     CredentialsType = "oidc"
+	CredentialsTypeTOTP     CredentialsType = "totp"
+	CredentialsTypeLookup   CredentialsType = "lookup_secret"
+	CredentialsTypeWebAuthn CredentialsType = "webauthn"
+	CredentialsTypeCodeAuth CredentialsType = "code"
+)
+
 func (c CredentialsType) String() string {
 	return string(c)
 }
@@ -101,16 +111,6 @@ func (c CredentialsType) ToUiNodeGroup() node.UiNodeGroup {
 	}
 }
 
-// Please make sure to add all of these values to the test that ensures they are created during migration
-const (
-	CredentialsTypePassword CredentialsType = "password"
-	CredentialsTypeOIDC     CredentialsType = "oidc"
-	CredentialsTypeTOTP     CredentialsType = "totp"
-	CredentialsTypeLookup   CredentialsType = "lookup_secret"
-	CredentialsTypeWebAuthn CredentialsType = "webauthn"
-	CredentialsTypeCodeAuth CredentialsType = "code"
-)
-
 var AllCredentialTypes = []CredentialsType{
 	CredentialsTypePassword,
 	CredentialsTypeOIDC,

identity/handler.go

@@ -257,7 +257,7 @@ type getIdentity struct {
 	//
 	// required: false
 	// in: query
-	DeclassifyCredentials []string `json:"include_credential"`
+	DeclassifyCredentials []CredentialsType `json:"include_credential"`
 }
 
 // swagger:route GET /admin/identities/{id} identity getIdentity
@@ -932,13 +932,11 @@ type deleteIdentityCredentials struct {
 	// in: path
 	ID string `json:"id"`
 
-	// Type is the credential's Type.
-	// One of totp, webauthn, lookup
+	// Type is the type of credentials to be deleted.
 	//
-	// enum: totp,webauthn,lookup
 	// required: true
 	// in: path
-	Type string `json:"type"`
+	Type CredentialsType `json:"type"`
 }
 
 // swagger:route DELETE /admin/identities/{id}/credentials/{type} identity deleteIdentityCredentials
@@ -977,19 +975,15 @@ func (h *Handler) deleteIdentityCredentials(w http.ResponseWriter, r *http.Reque
 	}
 
 	switch cred.Type {
-	case CredentialsTypeLookup:
-		fallthrough
-	case CredentialsTypeTOTP:
+	case CredentialsTypeLookup, CredentialsTypeTOTP:
 		identity.DeleteCredentialsType(cred.Type)
 	case CredentialsTypeWebAuthn:
 		identity, err = deletCredentialWebAuthFromIdentity(identity)
 		if err != nil {
 			h.r.Writer().WriteError(w, r, err)
 			return
 		}
-	case CredentialsTypeOIDC:
-		fallthrough
-	case CredentialsTypePassword:
+	case CredentialsTypeOIDC, CredentialsTypePassword, CredentialsTypeCodeAuth:
 		h.r.Writer().WriteError(w, r, errors.WithStack(herodot.ErrBadRequest.WithReasonf("You can't remove first factor credentials.")))
 		return
 	default:

identity/identity.go

@@ -33,7 +33,7 @@ import (
 //
 // The state can either be `active` or `inactive`.
 //
-// swagger:model identityState
+// swagger:enum State
 type State string
 
 const (

internal/client-go/.openapi-generator/FILES

@@ -44,11 +44,9 @@ docs/IdentityCredentialsCode.md
 docs/IdentityCredentialsOidc.md
 docs/IdentityCredentialsOidcProvider.md
 docs/IdentityCredentialsPassword.md
-docs/IdentityCredentialsType.md
 docs/IdentityPatch.md
 docs/IdentityPatchResponse.md
 docs/IdentitySchemaContainer.md
-docs/IdentityState.md
 docs/IdentityWithCredentials.md
 docs/IdentityWithCredentialsOidc.md
 docs/IdentityWithCredentialsOidcConfig.md
@@ -163,11 +161,9 @@ model_identity_credentials_code.go
 model_identity_credentials_oidc.go
 model_identity_credentials_oidc_provider.go
 model_identity_credentials_password.go
-model_identity_credentials_type.go
 model_identity_patch.go
 model_identity_patch_response.go
 model_identity_schema_container.go
-model_identity_state.go
 model_identity_with_credentials.go
 model_identity_with_credentials_oidc.go
 model_identity_with_credentials_oidc_config.go

internal/client-go/README.md

@@ -168,11 +168,9 @@ Class | Method | HTTP request | Description
  - [IdentityCredentialsOidc](docs/IdentityCredentialsOidc.md)
  - [IdentityCredentialsOidcProvider](docs/IdentityCredentialsOidcProvider.md)
  - [IdentityCredentialsPassword](docs/IdentityCredentialsPassword.md)
- - [IdentityCredentialsType](docs/IdentityCredentialsType.md)
  - [IdentityPatch](docs/IdentityPatch.md)
  - [IdentityPatchResponse](docs/IdentityPatchResponse.md)
  - [IdentitySchemaContainer](docs/IdentitySchemaContainer.md)
- - [IdentityState](docs/IdentityState.md)
  - [IdentityWithCredentials](docs/IdentityWithCredentials.md)
  - [IdentityWithCredentialsOidc](docs/IdentityWithCredentialsOidc.md)
  - [IdentityWithCredentialsOidcConfig](docs/IdentityWithCredentialsOidcConfig.md)