How do I generate API documentation for custom endpoints in IDM 5.5.x, 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
Overview
For IDM 7.1 and later, please refer to the documentation instead: Scripting Guide › Write an API Descriptor for a Custom Endpoint.
Pre-IDM 7.1
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 Samples Guide › 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
REST API Reference › REST API Explorer
Scripting Guide › Create Custom Endpoints to Launch Scripts
Related Training
N/A
Related Issue Tracker IDs
OPENIDM-12996 (DOCS: API Descriptor for scripted custom endpoint)