LinkedIn
Twitter
Update: April 23, 2019
A new major release of the WSDL Docs module (7.x-2.x) is now available on drupal.org. Please see the more recent Apigee Community article for updated installation and use instructions: https://community.apigee.com/articles/68137/documenting-soap-apis-on-devportal-using-the-wsdl-1.html
Background
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. The module is available on github: https://github.com/achieve-internet/wsdl_docs.
Devportals typically use the SmartDocs module to document RESTful (Representational State Transfer) APIs, however SmartDocs does not support SOAP/WSDL documentation by design.
The WSDL Docs module follows the model of the SmartDocs module by generating nodes for each operation and then rendering the SOAP trace form on each node. This allows 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.
Installation
To install the WSDL Docs module on a Devportal:
- Add the wsclient and wsdl_docs modules to the /sites/all/modules/contrib folder in your Drupal Devportal.
- Navigate to /admin/modules and enable the Web services client (wsclient), Web services client UI (wsclient_ui), and Web services client SOAP (wsclient_soap) modules available in the Services project
-
Also at /admin/modules and enable the WSDL Docs (wsdl_docs) and WSDL Docs Features (wsdl_features modules) available in the WSDL Docs project
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:
For Acquia, read more about the following topics:
For Private Cloud/OPDK, read more about the following:
The WSDL Docs module relies on the Web Services Client (WSClient) contributed module. WSClient provides an interface to consume external web services. WSClient comes with a user interface that allows site administrators to create SOAP ‘service’ descriptions as Drupal entities, with their respective operations as individual nodes.
Import via Drupal admin
There are a couple of different ways to import documentation using the WSDL Docs module. To import a WSDL via the Drupal admin, navigate to /admin/content/wsdl_docs/add.
Add the Service name, description, and URL of the Web Service. http://www.thomas-bayer.com/axis2/services/BLZService?wsdl is a useful web service to use for initial testing as it includes only one operation.
Click save and then view the operations that have been created for the service at /admin/content, filtering by Type: 'WSDL Docs Operation'.
To update a service, navigate to admin/content/wsdl_docs and select the edit option for the service to update. Click save once all desired changes have been made.
Import via REST Endpoint
WSDL documentation can also be imported via REST endpoint for continuous integration (CI/CD). To do this, first configure HTTP basic auth at /admin/content/wsdl_docs/basic_auth.
Basic auth functionality was added to the endpoint by copying some code from the Basic HTTP Authentication module. This leverages Drupal’s flood_register_event for extra security, by logging failed attempts to the ‘flood table’. Admins can view the IP address and timestamp of any failed POST to our endpoint, and a user can also add the Flood Control module to easily view these via the admin UI.
For imports via file upload POSTcontent-type: application/octet-stream to http://[my-devportal-url]/wsdl_docs_import?name=[service-name]
The ‘service’ name parameter passed in the URL is defined manually when importing via the Drupal admin UI.
For imports via URL parameter, POST content-type: application/x-www-form-urlencoded to http://[my-devportal-url]/wsdl_docs_import. The service name and URL of the WSDL file to import are included via Body parameters ‘name’ and ‘url’.
The following documentation uses Advanced REST Client (ARC) to send the POST request to the REST endpoint.
To import the WSDL via URL, configure ARC as follows:
- Method is POST
- Host is the devportal URL
- Path is /wsdl_docs_import
- Authorization:
- Authorization method: Basic authorization
- Set authorization data to the username/password entered at /admin/content/wsdl_docs/basic_auth
- Body:
- Body content type: application/x-www-form-urlencoded
- Editor view: Form data (www-url-form-encoded)
- Form Parameters:
- url: The web address of the WSDL.
- name: The human readable label of the webservice that appears at /soap_apis.
To import via file, configure ARC as follows:
- Method is POST
- Host is the devportal URL
- Path is /wsdl_docs_import
- Query parameter:
- name: The human readable label of the webservice that appears at /soap_apis.
- Authorization:
- Authorization method: Basic authorization
- Set authorization data to the username/password entered at /admin/content/wsdl_docs/basic_auth
- Body:
- Body content type: 'application/octet-stream' then choose file and upload.
Once configured, send. If successful, a 200 OK response will be returned along with response "Create [x] service" where x is the ID of the new service. If updating an existing service, when successful a 200 OK response will be returned along with response "UPDATE [x] SERVICE" where x is the ID of the new service.
Service entities
To view a list of services that have been imported using the WSDL Docs module, navigate to /soap_apis in the Devportal.
Clicking on a given service will send the user to that service’s page. This page is a Drupal view that lists all of a service’s operations nodes. Clicking on a given operation name will send the user to the individual operation node.
Operation nodes
Each operation node will display the documentation, style, and output for a given operation. Links to view the WSDL as human readable documentation using WSDL viewer as well as download the WSDL file as XML are included as well. A list related operations is also displayed by default to the left of the operation node. This list of related operations is generated by Drupal's views module (included in the Devportal).
After executing a request, the request and response are displayed below as tabs.
Support
This module is supported through community efforts and pull requests. For any customizations please contact Achieve Internet.
Important Acknowledgements
The WSDL Docs module was originally developed by Alex Borsody (https://www.drupal.org/u/alexborsody, https://github.com/alexborsody) working for Achieve Internet
