Documenting SOAP APIs on Devportal using the WSDL Docs Module - New Release  

Background

The WSDL Docs module was originally released as a contributed module on drupal.org in January 2019. A new major release, 7.x-2.x is now available on drupal.org.

Improvements

• Allows for the uploading of multiple WSDL files for a given SOAP API’s documentation
• Uses the contributed Services module to define a REST endpoint for creating, updating, and deleting SOAP API documentation
• Uses the Services module to configure basic HTTP authentication for making requests against the REST endpoint
• Unifies the syntax for creating SOAP API documentation via REST requests when using either a file or URL to define the WSDL resource
• Defines new permissions for making requests against the REST endpoint
• Fixes the display of operations nodes so WSDL files can be downloaded

The WSDL Docs module was developed for organizations who want to display WSDL (Web Service Definition Language) documentation for SOAP (Simple Object Access Protocol) APIs in an Apigee Devportal. As the SmartDocs module is often used on Devportals to document RESTful (Representational State Transfer) APIs, the WSDL Docs module follows the model of the SmartDocs module for documenting SOAP APIs.

The WSDL Docs module represents SOAP API documentation as a ‘service entity’ in the Devportal. For a given service entity, the module generates nodes for each operation and then renders the SOAP trace form on each node. This allows for SEO friendly navigation of documentation throughout the Devportal and the flexibility to display the operation nodes in views. The WSDL Docs module also allows sending of SOAP requests for operations, similar to the ‘Send this request’ functionality available for each REST method when using SmartDocs.

Set up

Install WSDL Docs on a Devportal

1. Add the wsdl_docs, wsclient, services_basic_auth modules to the /sites/all/modules/contrib folder in your Devportal. Note: the WSDL Docs module also depends on the entityreference, pathauto, and Services module. Entity reference and pathauto are provided as part of Apigee’s installation profile. Services is only provided in Apigee’s pantheon drupal drops repo, but if Apigee’s On-Prem Development Kit (OPDK) is being used to set up the Devportal, the Services module will also need to be added to the /sites/all/modules/contrib folder in your Devportal.
2. Navigate to /admin/modules and enable the wsdl_docs and wsdl_docs_features modules. You will be asked if dependencies should be enabled, and select yes.
3. Once this process is complete, the following modules should be enabled:

• wsclient
• wsclient_ui
• wsclient_soap
• entityreference
• pathauto
• services
• rest_server (part of Services)
• services_basic_auth
• wsdl_docs_features

If you are not familiar with how to add modules to your Devportal, Apigee provides great documentation for working with a cloud-based or on-prem Devportals:

For Pantheon, see the following resources:

• General background
• Git repo overview
• Deploying code
• Adding modules

For Acquia, read more about the following topics:

• General background
• Git repo overview
• Deploying code
• Adding modules:

For Private Cloud/OPDK, read more about the following:

• General background

Additional Setup

1. Ensure SOAP is installed on your server
2. Two permissions have been defined by the WSDL Docs module. Drupal’s permissions are configured at /admin/people/permissions. Permissions in Drupal are done on a per-role, rather than per-user basis.
   1. To allow users to make REST requests to create, update, and delete service entities using the WSDL Docs module, grant a role permission to ‘Make REST requests for WSDL Docs via Services’ Note: this module does some basic security checks of REST requests made against the WSDL Docs module. However, be very careful in selecting which role has permissions to make REST requests. This permission should only be assigned to very trusted user role(s).
   2. To allow users to download WSDL files that are imported in to a service entity, grant a role permission to ‘Download WSDL and XSD documents as displayed on operation nodes’.

Usage

The WSDL Docs module allows users to import WSDL documents to create SOAP API Documentation in two ways: via the Drupal administrative UI, and also via REST requests.

Create, view, and update SOAP API documentation via Drupal administrative UI

Create a service entity and its operations

1. Navigate to /admin/content/wsdl_docs/add
2. Give the service entity a name, description, and provide the URL of the WSDL resource.
3. Click the save button.

View a service entity and its operations

1. To view the list of service entities from the administrative section, go to admin/content/wsdl_docs
2. To view individual operation nodes from the administrative section, go to /admin/content and filter by Type: 'WSDL Docs Operation'
3. To view SOAP API documentation from the front end, select a service entity at /soap_apis. All of the service entity’s operations will be displayed via a table generated using Views.
4. To try out an operation, select an operation from the list on a service entity page.
5. Executing that request will display the following:
   1. the request that is being made (in raw form with headers and payload)
   2. the response that came back, also displaying
   3. the response headers and response data or message if any.
6. To download an WSDL file on an operation node, the user’s role must have been given the 'Download WSDL and XSD documents as displayed on operation nodes' permission.

Update a service entity and its operations

1. To update an existing service entity and its operations, select edit for a given service entity at admin/content/wsdl_docs, make desired changes, and save.

Create, update, and delete SOAP API documentation via REST requests

Configuring the Services module

1. At admin/structure/services/add, add your Service, select REST as the Server, select HTTP basic authentication for the authentication, and save. Your 'Path to endpoint' is referred to as [your-service-path-to-endpoint] in the sample REST requests below.
   

   

2. Once you've added your Service, click on the Edit Resources configuration option at admin/structure/services for your Service.
3. Under the WSDL resource, select the operations you want to make available (CUD available only right now) and save. Update allows you to update an existing service entity based on the URL of the WSDL resource. Import allows you to update an existing service entity based on uploaded file(s).
   

   

4. Make sure you have a user with the permission 'WSDL Docs Operations using Services module'. Use HTTP Basic Auth for these APIs. The username/password are the credentials for any account with 'WSDL Docs Operations using Services module' permissions setup on Devportal.

Create a service entity

The service entity must be created first before it can be updated with a WSDL resource (either a file or a URL) to add information about the service entity’s operations.

curl -X POST [your-website-url]/[your-service-path-to-endpoint]/wsdl \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [authorization hash]' \
-d '{"name": "[name of new service]"}'

Update a service entity’s operations by URL of WSDL resource

Once a service entity has been created, the service entity can be updated with a URL that refers to the WSDL resource.

curl -X PUT [your-website-url]/[your-service-path-to-endpoint]/wsdl/[wsdl-doc-machine-name] \
-H 'Authorization: Basic [authorization hash]' \
-H 'Content-Type: application/json' \
-d '{"url": "[URL of WSDL/XSD file ie 
http://www.thomas-bayer.com/axis2/services/BLZService?wsdl]"}'

Update a service entity’s operations by importing a WSDL file(s)

For importing multiple files, be sure the first file in the list is the main file that makes any references to additional files. The first file imported will be renamed [service-machine-name]-[service-id].[file extension (wsdl/xsd)] and saved to sites/default/private/wsdl_docs_files. If multiple files are imported, an archive of all of the files will be saved as [service-machine-name]-[service-id].zip.

curl -X POST [your-website-url]/[your-service-path-to-endpoint]/wsdl/[wsdl-doc-machine-name]/import \
-H 'Authorization: Basic [authorization hash]' \
-H 'content-type: multipart/form-data' \
-F 'soap_api_definition[]=@[path-to-main-wsdl]'
-F 'soap_api_definition[]=@[path-to-other-wsdls]'

Delete a service entity and its operations

curl -X DELETE [your-website-url]/[your-service-path-to-endpoint]/wsdl/[wsdl-doc-machine-name] \
-H 'Authorization: Basic [authorization hash]'

For information on the earlier 7.x-1.x version of this module, see the earlier Apigee Community article at https://community.apigee.com/content/kbentry/64767/documenting-soap-apis-on-devportal-using-the-wsdl.html

Support

This module is supported through community efforts and pull requests. For any customizations please contact Achieve Internet.