Document! X & HelpStudio Bundle 2022.1
Documentation Types / Web Service Documentation
In This Topic
    Web Service Documentation
    In This Topic

    Document! X and HelpStudio Bundle supports documentation of Web Services (SOAP and REST). Web Service documentation produces a comprehensive documentation set for your Web Services covering resource groups, operations, requests, responses, and parameters.

    Web Service Definition Source

    Document! X can use a variety of definition sources (WSDL, WADL, Swagger, WCF REST Help Page) to automatically determine the structure of your web service, or you can add an empty Web Service to the project and define the structure manually.

    SOAP Web Services

    To document SOAP Web Services, Document! X can directly read from a WSDL document (see Web Service Documentation Fundamentals for a step-by-step guide to adding a new Web Service and selecting WSDL File as the Web Service Definition Source).

    Most Web Services will publish a WSDL document automatically, typically available by calling the root service uri with a ?WSDL suffix, for example, http://api.microsofttranslator.com/V2/Soap.svc?WSDL.

    REST Web Services

    REST Web Services do not enjoy a single commonly implemented definition standard, but Document! X can automatically determine the structure of your web service using several different sources, which your web service may or may not already publish:

    WADL (Web Application Definition Language) Document: This REST version of the popular WSDL standard has not seen wide adoption, but if your web service architecture is able to generate a WADL document, Document! X can use it. See the Web Service Documentation Fundamentals for a step-by-step guide to adding a new Web Service and selecting WADL File as the Web Service Definition Source.

    OpenAPI/Swagger: An open standard specifically designed for documenting REST APIs. See the Web Service Documentation Fundamentals for a step-by-step guide to adding a new Web Service and selecting OpenAPI/Swagger API Definition as the Web Service Definition Source.

    WCF REST Help Page: If your REST service is implemented using WCF REST, a help page is automatically available that Document! X can use to determine the structure of your Web Service. The help page is available by calling the root service uri with a /Help suffix, for example, see http://msdn.microsoft.com/en-GB/library/ee230442.aspx for more information on the WCF REST Help Page. See the Web Service Documentation Fundamentals for a step-by-step guide to adding a new Web Service and selecting WCF REST Help Page as the Web Service Definition Source.

    ASP.NET Web API Help Page: If your REST service is implemented using ASP.NET Web API, Document! X can use the help pages feature to determine the structure of your Web Service, and to discover XML comments you have included in your service source code. For ASP.NET Web API 2, the help page's functionality is automatically included in the new project template. For earlier versions of Web API you can add this feature to your Web API project in Visual Studio as a NuGet package - see http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages for more information.

    If your web service does not publish structural information that Document! X can automatically read, you can still document your web service by defining the structure manually. See the Web Service Documentation Fundamentals for a step-by-step guide to adding a new Web Service and deselecting the Read Web Service Definition from an existing source option. You can then use commands on the context menu in the project explorer to add the Resource Groups, Resources, Operations, Requests, Responses, and Parameters that make up your web service.

    Leverage your Existing Content

    If you are documenting your Web Service from a Web Service Definition, Document! X will use any available descriptive content contained within the Web Service definition automatically. For example, the WSDL standard supports documentation elements which Document! X will use as the default summary for the related item.

    The level of support for defining descriptive content in the Web Service Definition depends on the technology you use to develop your web service. Refer to the documentation for the development tools you use to create your Web Service for more information.

    Web Service Documentation Fundamentals

    Create a New Web Service Documentation Project

    Create an Empty Project

    Creating an empty project creates a project without any content. You can customize its settings according to your needs.

    To create an empty project:

    1. Click the Application Button at the upper-left of the Ribbon Menu.
    2. Click New and then select Empty Project.

       

    3. Enter a project name in the Project Name field. 
      The project is created at the default directory which is configurable in the Options Editor (Paths page). However, you can optionally choose a specific directory to save your project by browsing the Project Directory field.
             
    4. Click OK.

    The new empty documentation project is created and opened for edit. You can now add the Web Service(s) that you want to document:

    1. On the Project tab, click the Add Web Service option.
    2. In the Add Web Service dialog,
      • Enter the web service name and web service title in the Web Service Name and Web Service Title fields.
      • If your web service does not expose a web service definition, clear the Read the Web Service structure from an existing source check box.
      • Select the Web Service Definition Type and specify the Location.
    3. Click OK.

    The Web Service is added to the Project Explorer under the Web Services node. You can expand down through the Web Service node to select/deselect individual elements in order to include/exclude them from the generated output. Repeat the process above to add additional Web Services to this project.

    A Content File is created and added to the project under the Content Files node for each added Web Service. You can use this Content File to author additional content in the pages that Document! X automatically generates.

    If your Web Service is a SOAP Web Service that includes embedded XSD Schemas, those XSD Schemas are also added to the Project and a Content File is created for each one so that you can document them together with the Web Service which uses them.

    Existing content from your Web Service Definition is automatically used in the generated output where available. Content from the Web Service Definition is displayed in the Content File Editor so you can see at a glance what content is already available from source comments and what requires further authoring.

    Author content for the Web Service

    If you would like to supplement the content of the pages automatically generated by Document! X and HelpStudio outside of the source code, you can do so using the Document! X and HelpStudio Content File Editor.

    The Content File Editor allows you to review and author content for any item for which a reference documentation page is generated.

    To open the Content File Editor:

    1. Expand the Content Files node on the Project Explorer.
    2. Locate the Content File for the item you wish to author content for.
    3. Right-click the Content File and select Edit.
    4. The Content File opened for edit. The tree on the left side of the editor shows you a hierarchical view of the item you are documenting.
    5. Drill down and select an item from the tree and the related documentation pages are shown in the right side of the editor.
    6. Select a specific content type from the toolbar/vertical menu to edit a specific type of content, for example, Summary, See Also, and Keywords.
    7. Type directly in the editable portions of the page on the right side of the editor.

    Add Conceptual Topics

    Conceptual information is a key part of reference documentation, providing a high level introduction, tutorials, or other conceptual information. You can easily create conceptual topics in Document! X and HelpStudio Bundle.

    1. Click the New Topic button on the Project tab or use the Ctrl+T shortcut key.
    2. The new Topic is created in the currently-selected Topic Category on the Project Explorer (or under the (Un-categorized) node if no category is selected) and opened for edit.

       

    3. Enter your conceptual content directly in the editable area of the Topic Editor.

    You can find more information on Topic Editing in the Topic Editor topic.

    Change Web Service Documentation Settings

    The settings that govern Web Service Documentation generation are defined in the Build Profile editor. In a new project there is a single Build Profile but you can define many build profiles if you want to create multiple outputs with different settings.

    To edit Web Service documentation settings:

    1. On the Project Explorer, expand the Build Profiles node.
    2. Double-click the required Build Profile to edit the properties.
      Alternatively, you can also right-click the required Build Profile and select Edit to open the Build Profile editor.

    In the Build Profile editor, you can find the Web Service Settings page under the Reference Documentation section.

    You can change the Template used for Web Service documentation (which defines the look and feel of generated pages) on the Templates page.

    Identify Undocumented Items

     An essential part of delivering a complete documentation set is ensuring that all the items have been documented. Document! X includes the Undocumented Items tool to quickly and easily identify undocumented items.

    1. On the Tools tab, select the Undocumented Items option.
    2. Select the profile in the Project Profile field for which you want to find the undocumented items.
      If your project contains only one Build Profile then it appears in the Project Profile field by default.
    3. Select Item Types, for example, Class, Method, Schema, and Column, that you want to check for undocumented items.
    4. Select Content Types to indicate the items that must be considered documented (just Summary by default).
    5. Select the Content Sources that should be used when checking for content.
    6. Select Execute. Any undocumented items will be listed in the results grid.

    Build and Deploy Web Service Reference Documentation

    You can modify the Build Profile settings to specify the Web Service settings such as resource path, request body detail, response body detail, and so on.

    On the Project tab, click the  Build button to build your Web Service reference documentation. 

    In a new project, the default Build Profile is configured to generate output in compiled CHM Html Help 1.x format.

    Refer to the Deployment topic for more information on how to deploy your documentation to other machines.