{ Community }
  • Academy
  • Docs
  • Developers
  • Resources
    • Community Articles
    • Apigee on GitHub
    • Code Samples
    • Videos & eBooks
    • Accelerator Methodology
  • Support
  • Ask a Question
  • Spaces
    • Product Announcements
    • General
    • Edge/API Management
    • Developer Portal (Drupal-based)
    • Developer Portal (Integrated)
    • API Design
    • APIM on Istio
    • Extensions
    • Business of APIs
    • Academy/Certification
    • Adapter for Envoy
    • Analytics
    • Events
    • Hybrid
    • Integration (AWS, PCF, Etc.)
    • Microgateway
    • Monetization
    • Private Cloud Deployment
    • 日本語コミュニティ
    • Insights
    • IoT Apigee Link
    • BaaS/Usergrid
    • BaaS Transition/Migration
    • Apigee-127
    • New Customers
    • Topics
    • Questions
    • Articles
    • Ideas
    • Leaderboard
    • Badges
  • Log in
  • Sign up

Get answers, ideas, and support from the Apigee Community

  • Home /
  • Developer Portal (Drupal-based) /
avatar image
2

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

  • Export to PDF
Kristin Brinner created · Apr 23, 2019 at 09:30 PM · 2.7k Views · edited · Apr 23, 2019 at 09:33 PM

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.

permissions.png (78.6 kB)
create-service.png (39.1 kB)
operation.png (276.5 kB)
services-config.png (120.8 kB)
crud-resources.png (77.0 kB)
thub.nodes.view.add-new-comment
Portal - DrupalSmartDocssoapwsdlwsdl import
Add comment Show 5
10 |5000 characters needed characters left characters exceeded
▼
  • Viewable by all users
  • Viewable by Apigeeks only
  • Viewable by the original poster
  • Viewable by moderators
  • Viewable by moderators and the original poster
  • Advanced visibility
Viewable by all users
avatar image Ashwith G · Aug 27, 2019 at 09:33 PM 0
Link

Hi @Kristin Brinner

I came across the below point in the post, how would I be able to install soap on the server, is it a module? if so, please give the details to proceed further

===========================================

Additional Setup

  1. Ensure SOAP is installed on your server

===========================================

Regards,

Ashwith


avatar image Kristin Brinner Ashwith G · Aug 27, 2019 at 09:45 PM 0
Link

You need the PHP SOAP extension to be enabled - see https://www.php.net/manual/en/book.soap.php for more information.

This is a requirement of the wsclient_soap module.

avatar image Andrew Rae · Mar 19, 2020 at 02:16 PM 0
Link

Is it possible to get this code packaged for Drupal 8?

avatar image Kristin Brinner Andrew Rae · Mar 19, 2020 at 05:24 PM 0
Link

Achieve is working with Google to plan a Drupal 8 version, but the work hasn't started. I'd be curious if anyone else following this thread was also looking for the D8 version of WSDL Docs.

avatar image si yin · Jan 13 at 08:13 PM 1
Link

do we have documentation for version wsdl_docs 3.0.0-beta3 on the same topic here - how to use REST request to create/update/delete soap api documentation?

Article

Contributors

avatar image

Follow this article

102 People are following this .

avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image

Navigation

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

Related Articles

Documenting SOAP APIs on Devportal using the WSDL Docs Module

Content Access Control on Developer Portal SmartDocs Documentation

SmartDocs and Swagger UI - A Comparison

APIs for publishing SmartDocs on Developer Portal

How to customize SmartDocs so that I can test against different environments from the same page

SmartDocs role based access control

SmartDocs - A custom module to your rescue - Fix for SmartDocs issues

Apigee Developer Portal - Go Live Check List

Exception thrown while creating Smart Docs using JSON

How to add a left nav to SmartDocs Method page to list all operations of the current model

  • Products
    • Edge - APIs
    • Insights - Big Data
    • Plans
  • Developers
    • Overview
    • Documentation
  • Resources
    • Overview
    • Blog
    • Apigee Institute
    • Academy
    • Documentation
  • Company
    • Overview
    • Press
    • Customers
    • Partners
    • Team
    • Events
    • Careers
    • Contact Us
  • Support
    • Support Overview
    • Documentation
    • Status
    • Edge Support Portal
    • Privacy Policy
    • Terms & Conditions
© 2021 Apigee Corp. All rights reserved. - Apigee Community Terms of Use - Powered by AnswerHub
  • Anonymous
  • Sign in
  • Create
  • Ask a question
  • Create an article
  • Post an idea
  • Spaces
  • Product Announcements
  • General
  • Edge/API Management
  • Developer Portal (Drupal-based)
  • Developer Portal (Integrated)
  • API Design
  • APIM on Istio
  • Extensions
  • Business of APIs
  • Academy/Certification
  • Adapter for Envoy
  • Analytics
  • Events
  • Hybrid
  • Integration (AWS, PCF, Etc.)
  • Microgateway
  • Monetization
  • Private Cloud Deployment
  • 日本語コミュニティ
  • Insights
  • IoT Apigee Link
  • BaaS/Usergrid
  • BaaS Transition/Migration
  • Apigee-127
  • New Customers
  • Explore
  • Topics
  • Questions
  • Articles
  • Ideas
  • Badges