How do I generate API documentation for custom endpoints in IDM 6.x and 7?
The purpose of this article is to provide information on generating API documentation for IDM custom endpoints.
1 reader recommends this article
Note
This article does not apply to IDM 7.1 and later, because it is included in the documentation: Write an API descriptor for a custom endpoint.
Overview
The IDM API Explorer provides API documentation for IDM’s default endpoints, for example:
However, documentation is not automatically generated for custom endpoints. You can use the API Explorer to generate reference documentation for custom endpoints by including an apiDescription field in the endpoint’s configuration file.
Generating API documentation for custom endpoints example
The following example demonstrates how to do this for the sample custom endpoint (echo) and assumes you have already created the custom endpoint. See Create a custom endpoint for further information.
Note
If you want to add "If-None-Match" and "If-Match" header parameters to Read requests and Delete/Patch requests, you should set the mvccSupported property to 'true'. You do not need to add “if-match” and “if-none-match” specifically to the request parameters.
You can generate API documentation for a custom endpoint as follows:
- Add the apiDescription field to the endpoint configuration file (/path/to/idm/conf/endpoint-echo.json in this example) to include all the actions and queries you want documented. See Forgerock Wiki - Defining API Descriptors for further assistance.
For example:{ "file" : "echo.groovy", "type" : "groovy", "_file" : "echo.js", "_type" : "text/javascript", "apiDescription" : { "title" : "Echo", "description" : "Service that echo's your HTTP requests.", "mvccSupported" : true, "create" : { "description" : "Echo a CREATE request.", "mode" : "ID_FROM_SERVER", "singleton" : false }, "read" : { "description" : "Echo a READ request." }, "update" : { "description" : "Echo an UPDATE request." }, "delete" : { "description" : "Echo a DELETE request." }, "patch" : { "description" : "Echo a PATCH request.", "operations" : [ "ADD", "REMOVE", "REPLACE", "INCREMENT", "COPY", "MOVE", "TRANSFORM" ] }, "actions" : [ { "description" : "Echo an ACTION request.", "name" : "echo", "request" : { "type" : "object" }, "response" : { "title" : "Echo action response", "type" : "object", "properties" : { "method" : { "type" : "string", "enum" : [ "action" ] }, "action" : { "type" : "string" }, "content" : { "type" : "object" }, "parameters" : { "type" : "object" }, "context" : { "type" : "object" } } } } ], "queries" : [ { "description" : "Echo a query-filter request.", "type" : "FILTER", "queryableFields" : [ "*" ] }, { "description" : "Echo a query-all request.", "type" : "ID", "queryId" : "query-all" }, { "description" : "Echo a query-all-ids request.", "type" : "ID", "queryId" : "query-all-ids" } ], "resourceSchema" : { "title" : "Echo resource", "type" : "object", "properties" : { "method" : { "title" : "CREST method", "type" : "string" }, "resourceName" : { "type" : "string" }, "parameters" : { "type" : "object" }, "context" : { "type" : "object" } } } } }
- Review the API Explorer to check that your custom endpoint is now included, for example:
See Also
Create custom endpoints to launch scripts
Forgerock Wiki - Defining API Descriptors
Using the ForgeRock IDM API Explorer
Related Training
N/A
Related Issue Tracker IDs
N/A