mirror of
https://github.com/logto-io/logto.git
synced 2025-03-17 22:31:28 -05:00
chore(core): add openapi operationId to experience APIs (#6486)
* chore(core): add openapi operationId to experience APIs add openapi operationId to experience APIs * chore: update content update content * feat(core): add swagger operationId guard add swagger operationId guard * fix: update some content update some content
This commit is contained in:
simeng-li
GitHub
parent
2ebc47170e
commit
55cf84bbea
13 changed files with 69 additions and 40 deletions
|
|
@ -2,7 +2,8 @@
|
|||
"paths": {
|
||||
"/api/experience/sso-connectors": {
|
||||
"get": {
|
||||
"summary": "Get all the enabled SSO connectors by the given email's domain",
|
||||
"operationId": "GetEnabledSsoConnectors",
|
||||
"summary": "Get enabled SSO connectors by the given email's domain",
|
||||
"description": "Extract the email domain from the provided email address. Returns all the enabled SSO connectors that match the email domain.",
|
||||
"parameters": [
|
||||
{
|
||||
|
|
|
|||
|
|
@ -8,8 +8,9 @@
|
|||
"paths": {
|
||||
"/api/experience": {
|
||||
"put": {
|
||||
"summary": "Init a new experience interaction",
|
||||
"description": "Init a new experience interaction with the given interaction type. Any existing experience interaction data will be cleared.",
|
||||
"operationId": "InitInteraction",
|
||||
"summary": "Init new interaction",
|
||||
"description": "Init a new experience interaction with the given interaction type. Any existing interaction data will be cleared.",
|
||||
"responses": {
|
||||
"204": {
|
||||
"description": "A new experience interaction has been successfully initiated."
|
||||
|
|
@ -19,7 +20,8 @@
|
|||
},
|
||||
"/api/experience/interaction-event": {
|
||||
"put": {
|
||||
"summary": "Update current experience interaction event",
|
||||
"operationId": "UpdateInteractionEvent",
|
||||
"summary": "Update interaction event",
|
||||
"description": "Update the current experience interaction event to the given event type. This API is used to switch the interaction event between `SignIn` and `Register`, while keeping all the verification records data.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
|
|
@ -49,7 +51,8 @@
|
|||
},
|
||||
"/api/experience/identification": {
|
||||
"post": {
|
||||
"summary": "Identify the user within the current experience interaction using the provided verification data",
|
||||
"operationId": "IdentifyUser",
|
||||
"summary": "Identify user for the current interaction",
|
||||
"description": "This API identifies the user based on the verificationId within the current experience interaction: <br/>- `SignIn` and `ForgotPassword` interactions: Verifies the user's identity using the provided `verificationId`. <br/>- `Register` interaction: Creates a new user account using the profile data from the current interaction. If a verificationId is provided, the profile data will first be updated with the verification record before creating the account. If not, the account is created directly from the stored profile data.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
|
|
@ -97,7 +100,8 @@
|
|||
},
|
||||
"/api/experience/submit": {
|
||||
"post": {
|
||||
"summary": "Submit experience interaction",
|
||||
"operationId": "SubmitInteraction",
|
||||
"summary": "Submit interaction",
|
||||
"description": "Submit the current interaction. <br/>- Submit the verified user identity to the OIDC provider for further authentication (SignIn and Register). <br/>- Update the user's profile data if any (SignIn and Register). <br/>- Reset the password and clear all the interaction records (ForgotPassword).",
|
||||
"responses": {
|
||||
"200": {
|
||||
|
|
|
|||
|
|
@ -2,7 +2,8 @@
|
|||
"paths": {
|
||||
"/api/experience/profile": {
|
||||
"post": {
|
||||
"summary": "Fulfill user profile data",
|
||||
"operationId": "UpdateUserProfile",
|
||||
"summary": "Update user profile data",
|
||||
"description": "Adds user profile data to the current experience interaction. <br/>- For `Register`: The profile data provided before the identification request will be used to create a new user account. <br/>- For `SignIn` and `Register`: The profile data provided after the user is identified will be used to update the user's profile when the interaction is submitted. <br/>- `ForgotPassword`: Not supported.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
|
|
@ -34,7 +35,7 @@
|
|||
"description": "Entity not found. <br/> - `session.identifier_not_found:` (`SignIn` interaction only) The current interaction is not identified yet. All profile data must be associated with a identified user. <br/>- `session.verification_session_not_found:` The verification record is not found."
|
||||
},
|
||||
"403": {
|
||||
"description": "`SignIn` interaction only: Multi-Factor Authentication (MFA) is enabled for the user but has not been verified. The user must verify the MFA before updating the profile data."
|
||||
"description": "`SignIn` interaction only: MFA is enabled for the user but has not been verified. The user must verify the MFA before updating the profile data."
|
||||
},
|
||||
"422": {
|
||||
"description": "The user profile can not been processed, check error message for more details. <br/>- The profile data is invalid or conflicts with existing user data. <br/>- The profile data is already in use by another user account."
|
||||
|
|
@ -44,8 +45,9 @@
|
|||
},
|
||||
"/api/experience/profile/password": {
|
||||
"put": {
|
||||
"operationId": "ResetUserPassword",
|
||||
"summary": "Reset user password",
|
||||
"description": "Update the user's password. (`ForgotPassword` interaction only)",
|
||||
"description": "Reset the user's password. (`ForgotPassword` interaction only)",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
@ -77,7 +79,8 @@
|
|||
},
|
||||
"/api/experience/profile/mfa/mfa-skipped": {
|
||||
"post": {
|
||||
"summary": "Skip Multi-Factor Authentication (MFA) binding flow",
|
||||
"operationId": "SkipMfaBindingFlow",
|
||||
"summary": "Skip MFA binding flow",
|
||||
"description": "Skip MFA verification binding flow. If the MFA is enabled in the sign-in experience settings and marked as `UserControlled`, the user can skip the MFA verification binding flow by calling this API.",
|
||||
"responses": {
|
||||
"204": {
|
||||
|
|
@ -100,7 +103,8 @@
|
|||
},
|
||||
"/api/experience/profile/mfa": {
|
||||
"post": {
|
||||
"summary": "Bind Multi-Factor Authentication (MFA) verification by verificationId",
|
||||
"operationId": "BindMfaVerification",
|
||||
"summary": "Bind MFA verification by verificationId",
|
||||
"description": "Bind new MFA verification to the user profile using the verificationId.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/backup-code/generate": {
|
||||
"post": {
|
||||
"operationId": "GenerateBackupCodes",
|
||||
"summary": "Generate backup codes",
|
||||
"description": "Generate backup codes for the current user. A new BackupCode verification record will be created in the current interaction.",
|
||||
"description": "Create a new BackupCode verification record with new backup codes generated. This verification record will be used to bind the backup codes to the user's profile.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Backup codes have been successfully generated.",
|
||||
|
|
@ -30,8 +31,9 @@
|
|||
},
|
||||
"/api/experience/verification/backup-code/verify": {
|
||||
"post": {
|
||||
"operationId": "VerifyBackupCode",
|
||||
"summary": "Verify backup code",
|
||||
"description": "Verify the provided backup code against the user's backup codes. A new BackupCode verification record will be created and marked as verified if the code is correct.",
|
||||
"description": "Create a new BackupCode verification record and verify the provided backup code against the user's backup codes. The verification record will be marked as verified if the code is correct.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/sso/{connectorId}/authorization-uri": {
|
||||
"post": {
|
||||
"summary": "Get SSO authorization URI",
|
||||
"description": "Create a new EnterpriseSSO verification record and return the authorization URI for the given connector.",
|
||||
"operationId": "CreateEnterpriseSsoVerification",
|
||||
"summary": "Create enterprise SSO verification",
|
||||
"description": "Create a new EnterpriseSSO verification record and return the provider's authorization URI for the given connector.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
@ -49,8 +50,9 @@
|
|||
},
|
||||
"/api/experience/verification/sso/{connectorId}/verify": {
|
||||
"post": {
|
||||
"summary": "Verify SSO authorization response",
|
||||
"description": "Verify the SSO authorization response data and get the user's profile data from the SSO connector.",
|
||||
"operationId": "VerifyEnterpriseSsoVerification",
|
||||
"summary": "Verify enterprise SSO verification",
|
||||
"description": "Verify the SSO authorization response data and get the user's identity from the SSO provider.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/new-password-identity": {
|
||||
"post": {
|
||||
"summary": "Create a new password identity for new user registration use",
|
||||
"description": "Create a NewPasswordIdentity verification record for the new user registration use. The verification record includes a unique user identifier and a password that can be used to verify the user's identity.",
|
||||
"operationId": "CreateNewPasswordIdentityVerification",
|
||||
"summary": "Create new password identity verification",
|
||||
"description": "Create a NewPasswordIdentity verification record for the new user registration use. The verification record includes a unique user identifier and a password that can be used to create a new user account.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/password": {
|
||||
"post": {
|
||||
"summary": "Create and verify a new password verification record",
|
||||
"description": "Generate a new Password verification record, which can be used to identify the user through the `Identification` API.",
|
||||
"operationId": "CreatePasswordVerification",
|
||||
"summary": "Create password verification record",
|
||||
"description": "Create and verify a new Password verification record. The verification record can only be created if the provided user credentials are correct.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/social/{connectorId}/authorization-uri": {
|
||||
"post": {
|
||||
"summary": "Get social authorization URI",
|
||||
"description": "Create a new SocialVerification record and return the authorization URI for the given connector.",
|
||||
"operationId": "CreateSocialVerification",
|
||||
"summary": "Create social verification",
|
||||
"description": "Create a new SocialVerification record and return the provider's authorization URI for the given connector.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
@ -49,8 +50,9 @@
|
|||
},
|
||||
"/api/experience/verification/social/{connectorId}/verify": {
|
||||
"post": {
|
||||
"summary": "Verify social authorization response",
|
||||
"description": "Verify the social authorization response data and get the user's profile data from the social connector.",
|
||||
"operationId": "VerifySocialVerification",
|
||||
"summary": "Verify social verification",
|
||||
"description": "Verify the social authorization response data and get the user's identity data from the social provider.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/totp/secret": {
|
||||
"post": {
|
||||
"summary": "Generate TOTP secret for new TOTP binding",
|
||||
"description": "Creates a new TOTP secret for the user to bind a new TOTP verification to their account.",
|
||||
"operationId": "CreateTotpSecret",
|
||||
"summary": "Create TOTP secret",
|
||||
"description": "Create a new TOTP verification record and generate a new TOTP secret for the user. This secret can be used to bind a new TOTP verification to the user's profile. The verification record must be verified before the secret can be used to bind a new TOTP verification to the user's profile.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "TOTP secret successfully generated.",
|
||||
|
|
@ -33,8 +34,9 @@
|
|||
},
|
||||
"/api/experience/verification/totp/verify": {
|
||||
"post": {
|
||||
"summary": "Verify TOTP code",
|
||||
"description": "Verifies the provided TOTP code against the user's TOTP secret. If the code is correct, a new TOTP verification record will be created and marked as verified..",
|
||||
"operationId": "VerifyTotpVerification",
|
||||
"summary": "Verify TOTP verification",
|
||||
"description": "Verifies the provided TOTP code against the new created TOTP secret or the existing TOTP secret. If a verificationId is provided, this API will verify the code against the TOTP secret that is associated with the verification record. Otherwise, a new TOTP verification record will be created and verified against the user's existing TOTP secret.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/verification-code": {
|
||||
"post": {
|
||||
"operationId": "CreateAndSendVerificationCode",
|
||||
"summary": "Create and send verification code",
|
||||
"description": "Creates a new `CodeVerification` record and sends the code to the specified identifier. The code verification can be used to verify the user's identity or bind a new identifier to the user's account.",
|
||||
"description": "Create a new `CodeVerification` record and sends the code to the specified identifier. The code verification can be used to verify the given identifier.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
@ -46,8 +47,9 @@
|
|||
},
|
||||
"/api/experience/verification/verification-code/verify": {
|
||||
"post": {
|
||||
"operationId": "VerifyVerificationCode",
|
||||
"summary": "Verify verification code",
|
||||
"description": "Verifies the provided verification code against the user's identifier. If successful, the verification record is marked as verified.",
|
||||
"description": "Verify the provided verification code against the user's identifier. If successful, the verification record will be marked as verified.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -2,8 +2,9 @@
|
|||
"paths": {
|
||||
"/api/experience/verification/web-authn/registration": {
|
||||
"post": {
|
||||
"summary": "Create WebAuthn registration",
|
||||
"description": "Creates a new WebAuthn registration verification record to allow the user to bind a new WebAuthn credential to their account.",
|
||||
"operationId": "CreateWebAuthnRegistrationVerification",
|
||||
"summary": "Create WebAuthn registration verification",
|
||||
"description": "Create a new WebAuthn registration verification record. The verification record can be used to bind a new WebAuthn credential to the user's profile.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "WebAuthn registration successfully created.",
|
||||
|
|
@ -30,8 +31,9 @@
|
|||
},
|
||||
"/api/experience/verification/web-authn/registration/verify": {
|
||||
"post": {
|
||||
"summary": "Verify WebAuthn registration",
|
||||
"description": "Verifies the WebAuthn registration response against the user's WebAuthn registration challenge. If the response is valid, the WebAuthn registration record will be marked as verified.",
|
||||
"operationId": "VerifyWebAuthnRegistrationVerification",
|
||||
"summary": "Verify WebAuthn registration verification",
|
||||
"description": "Verify the WebAuthn registration response against the user's WebAuthn registration challenge. If the response is valid, the WebAuthn registration record will be marked as verified.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
@ -74,8 +76,9 @@
|
|||
},
|
||||
"/api/experience/verification/web-authn/authentication": {
|
||||
"post": {
|
||||
"summary": "Initiate WebAuthn authentication",
|
||||
"description": "Creates a new WebAuthn authentication verification record, allowing the user to authenticate with their WebAuthn credential.",
|
||||
"operationId": "CreateWebAuthnAuthenticationVerification",
|
||||
"summary": "Create WebAuthn authentication verification",
|
||||
"description": "Create a new WebAuthn authentication verification record based on the user's existing WebAuthn credential. This verification record can be used to verify the user's WebAuthn credential.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "WebAuthn authentication successfully initiated.",
|
||||
|
|
@ -105,8 +108,9 @@
|
|||
},
|
||||
"/api/experience/verification/web-authn/authentication/verify": {
|
||||
"post": {
|
||||
"summary": "Verify WebAuthn authentication",
|
||||
"description": "Verifies the WebAuthn authentication response against the user's authentication challenge. Upon successful verification, the WebAuthn authentication verification record will be marked as verified.",
|
||||
"operationId": "VerifyWebAuthnAuthenticationVerification",
|
||||
"summary": "Verify WebAuthn authentication verification",
|
||||
"description": "Verifies the WebAuthn authentication response against the user's authentication challenge. Upon successful verification, the verification record will be marked as verified.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
|
|
|||
|
|
@ -232,6 +232,10 @@ export const validateSwaggerDocument = (document: OpenAPIV3.Document) => {
|
|||
operation.description,
|
||||
`Path \`${path}\` and operation \`${method}\` must have a description.`
|
||||
);
|
||||
assert(
|
||||
operation.operationId,
|
||||
`Path \`${path}\` and operation \`${method}\` must have an operationId.`
|
||||
);
|
||||
}
|
||||
|
||||
for (const tag of document.tags ?? []) {
|
||||
|
|
|
|||
|
|
@ -163,7 +163,7 @@ export const buildOperationId = (method: OpenAPIV3.HttpMethods, path: string) =>
|
|||
}
|
||||
|
||||
// Skip interactions APIs as they are going to replaced by the new APIs soon.
|
||||
// Skip experience APIs as they are not strictly RESTful.
|
||||
// Skip experience APIs, as all the experience APIs' `operationId` will be customized in the custom openapi.json documents.
|
||||
if (path.startsWith('/interaction') || path.startsWith('/experience')) {
|
||||
return;
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue