mirror of
https://github.com/logto-io/logto.git
synced 2025-01-06 20:40:08 -05:00
chore(core): add connector api doc descriptions (#5042)
* chore(core): add connector api doc descriptions * chore(core): polish docs --------- Co-authored-by: Gao Sun <gao@silverhand.io>
This commit is contained in:
Darcy Ye
GitHub
parent
88e8aa944a
commit
f539b0851d
5 changed files with 255 additions and 0 deletions
|
|
@ -0,0 +1,48 @@
|
|||
{
|
||||
"paths": {
|
||||
"/api/connectors/{id}/authorization-uri": {
|
||||
"post": {
|
||||
"summary": "Get connector's authorization URI",
|
||||
"description": "Get authorization URI for specified connector by providing redirect URI and randomly generated state.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"properties": {
|
||||
"redirectUri": {
|
||||
"description": "The URI to navigate back to after the user is authenticated by the connected social identity provider and has granted access to the connector."
|
||||
},
|
||||
"state": {
|
||||
"description": "A random string generated on the client side to prevent CSRF (Cross-Site Request Forgery) attacks."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successfully built authorization URI.",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"properties": {
|
||||
"redirectUri": {
|
||||
"description": "The URI to navigate for authentication and authorization in the connected social identity provider."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Unable to build authorization URI."
|
||||
},
|
||||
"404": {
|
||||
"description": "The connector with the specified ID does not exist."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
{
|
||||
"paths": {
|
||||
"/api/connectors/:factoryId/test": {
|
||||
"post": {
|
||||
"summary": "Test passwordless connector",
|
||||
"description": "Test a passwordless (email or SMS) connector by sending a test message to the given phone number or email address.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"properties": {
|
||||
"phone": {
|
||||
"description": "Phone number to send test message to. If this is set, email will be ignored."
|
||||
},
|
||||
"email": {
|
||||
"description": "Email address to send test message to. If phone is set, this will be ignored."
|
||||
},
|
||||
"config": {
|
||||
"description": "Connector configuration object for testing."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"204": {
|
||||
"description": "Test message was sent successfully."
|
||||
},
|
||||
"400": {
|
||||
"description": "Invalid request body (e.g. wrong phone number, email or config)."
|
||||
},
|
||||
"404": {
|
||||
"description": "Connector not found."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -34,6 +34,7 @@ export default function connectorConfigTestingRoutes<T extends AuthedRouter>(
|
|||
email: string().regex(emailRegEx).optional(),
|
||||
config: jsonObjectGuard,
|
||||
}),
|
||||
status: [204, 400, 404],
|
||||
}),
|
||||
async (ctx, next) => {
|
||||
const {
|
||||
|
|
|
|||
35
packages/core/src/routes/connector/factory.openapi.json
Normal file
35
packages/core/src/routes/connector/factory.openapi.json
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
{
|
||||
"tags": [
|
||||
{
|
||||
"name": "Connector factories",
|
||||
"description": "Connector factories are used to create connectors. They can be treated as preconfigured templates for connectors."
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/api/connector-factories": {
|
||||
"get": {
|
||||
"summary": "Get connector factories",
|
||||
"description": "Get all connector factories data available in Logto.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "An array of connector factories."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/connector-factories/{id}": {
|
||||
"get": {
|
||||
"summary": "Get connector factory",
|
||||
"description": "Get connector factory by the given ID.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Connector factory data."
|
||||
},
|
||||
"404": {
|
||||
"description": "Connector factory not found."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
131
packages/core/src/routes/connector/index.openapi.json
Normal file
131
packages/core/src/routes/connector/index.openapi.json
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
{
|
||||
"tags": [
|
||||
{
|
||||
"name": "Connectors",
|
||||
"description": "Connectors are the bridge between Logto and other third-party vendors who provide short message service (SMS), email service, or user information on wildly accepted social media.\n\nTo learn more about connectors, please see [🪛 Configure connectors](https://docs.logto.io/docs/recipes/configure-connectors/)."
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/api/connectors": {
|
||||
"post": {
|
||||
"summary": "Create connector",
|
||||
"description": "Create a connector with the given data.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"properties": {
|
||||
"id": {
|
||||
"description": "The unique ID for the connector. If not provided, a random ID will be generated."
|
||||
},
|
||||
"connectorId": {
|
||||
"description": "The connector factory ID for creating the connector."
|
||||
},
|
||||
"syncProfile": {
|
||||
"description": "Whether to sync user profile from the identity provider to Logto at each sign-in. If `false`, the user profile will only be synced when the user is created."
|
||||
},
|
||||
"config": {
|
||||
"description": "The connector config object that will be passed to the connector. The config object should be compatible with the connector factory."
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Custom connector metadata, will be used to overwrite the default connector factory metadata."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "The created connector."
|
||||
},
|
||||
"422": {
|
||||
"description": "Invalid request body."
|
||||
}
|
||||
}
|
||||
},
|
||||
"get": {
|
||||
"summary": "Get connectors",
|
||||
"description": "Get all connectors in the current tenant.",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "target",
|
||||
"in": "query",
|
||||
"description": "Filter connectors by target."
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "An array of connectors."
|
||||
},
|
||||
"400": {
|
||||
"description": "The target only allows one connector to exist, but there are multiple connectors with this target."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/connectors/{id}": {
|
||||
"get": {
|
||||
"summary": "Get connector",
|
||||
"description": "Get connector data by ID",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "The connector data."
|
||||
},
|
||||
"404": {
|
||||
"description": "Connector not found."
|
||||
}
|
||||
}
|
||||
},
|
||||
"patch": {
|
||||
"summary": "Update connector",
|
||||
"description": "Update connector by ID with the given data. This methods performs a partial update.",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"properties": {
|
||||
"syncProfile": {
|
||||
"description": "Whether to sync user profile from the identity provider to Logto at each sign-in. If `false`, the user profile will only be synced when the user is created."
|
||||
},
|
||||
"config": {
|
||||
"description": "The connector config object that will be passed to the connector. The config object should be compatible with the connector factory."
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Custom connector metadata, will be used to overwrite the default connector metadata."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "The updated connector."
|
||||
},
|
||||
"400": {
|
||||
"description": "Invalid request body."
|
||||
},
|
||||
"404": {
|
||||
"description": "Connector not found."
|
||||
},
|
||||
"422": {
|
||||
"description": "Patch operation triggered a connector conflict."
|
||||
}
|
||||
}
|
||||
},
|
||||
"delete": {
|
||||
"summary": "Delete connector",
|
||||
"description": "Delete connector by ID.",
|
||||
"responses": {
|
||||
"204": {
|
||||
"description": "The connector has been successfully deleted."
|
||||
},
|
||||
"404": {
|
||||
"description": "Connector not found."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue