Skip to content

Add API Documentation

API documentation helps API subscribers understand the functionality of the API, and API publishers to market their APIs better and sustain competition. Using the API Publisher, you can add different types of documentation from different sources. All documents created in the API Publisher have unique URLs to help improve SEO support.

The documentation types supported in the API Publisher are as follows:

  • In-line: Hosts documentation (How-tos, Samples, SDK, forums etc.) in WSO2 API Publisher itself and allows it to be edited directly from the UI.
  • URL: Links of public or support forums or file references (URLs) of an external configuration management system.
  • File: Allows to upload the documentation directly to the server.
  • Markdown: Allows to add markdown (md) docs via a Markdown editor.

Follow the steps below to learn how to add a documentation to an API.

  1. Sign in to the WSO2 API Publisher. https://<hostname>:9443/publisher

  2. Click the API (e.g., PizzaShackAPI 1.0.0 ) for which you want to add documentation.

  3. Follow the steps below for each type.

    Add in-line documentation

    1. Select the Documents tab of the API and click Add New Document .
    2. Enter the following details to create documentation in-line.

      Name PizzaShack
      Summary This is the official documentation for the PizzaShack API
      Type How To
      Source In-line

    3. Click Add Document .

    4. Click Add Content to open an embedded editor.

      Note

      You can edit the content later by clicking Edit Content. It will open up the embedded editor to proceed.

      Info

      Edit button can be used to update/change the document information.

    5. Edit the document content in-line using the embedded editor and click Update Content. The API's Documents tab opens.

    Add documentation using a URL

    You can use either Public Forum, Support Forum or Other types to add documentation using a URL.

    1. Click Add New Document to add another doc type.

    2. Enter the following information to create another doc using a URL of a Public or Support forum.

      Name API Forum
      Summary

      Forum to discuss about APIs

      Type Public Forum/Support Forum
      Source URL
      http://www.dummyforum.com

    3. Enter the following information to create another doc using a URL. This can be used if you want to add a documentation using Other type pointing to a link to a file reference of an external source.

      Name PizzaShack Wiki
      Summary

      Sample PizzaShack API

      Type Other
      Other Document Type Other (Provide a type as required)
      Source URL
      http://www.dummy.com/PizzaShackAPIDoc.pdf

    4. Click Add Document . The API's Documents tab opens.

    Add documentation using a file

    1. Click Add New Document to add yet another document using a file.

    2. Enter the following information.

      Name API Manager Samples
      Summary API Manager Samples
      Type Samples & SDK
      Source You can provide any file format (common formats are .pdf , .html , .doc , .txt ) of any size. For example, use the sample PDF file here .

    3. Click Add Document.

    Add markdown documentation

    1. Select the Documents tab of the API and click Add New Document .

    2. Enter the following details to create documentation in-line and click Add Document.

      Name PizzaShackAPI Documentation
      Summary This is the official documentation for the PizzaShack API
      Type How To
      Source Markdown

    3. Click Add Content to open an embedded editor.

    4. Edit the document content using the embedded markdown editor and click Update Content.

    5. The API's Documents tab opens.

  4. You have now added four documents to the API: in-line, using a URL, using a file and markdown type.

  5. Log in to the WSO2 Developer Portal and click the PizzaShackAPI 1.0.0 version. https://<hostname>:9443/devportal

  6. Go to the API's Documentation tab and see the documents listed by type. Click the links to see the documentation content. As a subscriber, you can read the documentation and learn about the API.

You have created documentation using the API Publisher and viewed them as a subscriber in the Develper Portal.

Top