Documentation
 

Search Results

Creating API Documentation

At this point, you can potentially test you API using your favorite client app. (For example, enter http://evalXXXX.api.mashery.com/acme/v1?api_key=25puf2ft6d9y6zrud3cc49zj in a browser). But first, you need to create an interactive documentation page called I/O Docs.

To clarify what the following steps do, setting up I/O Docs doesn't affect which resources are available via Mashery. At present, you have defined it so that all services exposed via https://integration.cloud.tibcoapps.com are available via http://evalXXXX.api.mashery.com/acme/v1. What you are configuring is how a portal user can interact with the services via the I/O Docs page on the portal.

To begin creating API documentation:

Procedure

  1. Return to the API Control Center dashboard, then navigate to Design > I/O Docs on the top menu. The I/O Docs page shows a list of all the APIs defined.

    Note: You can click on the I/O Docs Settings button on the top right to modify the general settings for the I/O Docs Page Title and Description. You do not need to make any changes to these options for this quick start example.


  2. Click on Acme API to open the default I/O Docs template that has been created based on the API and Endpoint definitions created in earlier sections.

    Note: On the top right of the page is an Import button that allows for importing an existing IO Docs JSON file or WSDL (for Web Services proxied through Mashery).

  3. In order to point I/O Docs to the appropriate API endpoint and paths for each method, make the following edits in the I/O Docs JSON file:
    • "baseplate": "http://evalXXXX.api.mashery.com/acme/v1"
    • Under "exampleMethod":
      • "description": "Get all products"
      • "path": "/product"
    • Under the "parameters", there is a sample "exampleParameter" created; change "required" to false.
    • (Optional) You can also change the names of the methods (for example, instead of exampleMethod, you can use GetAllProducts), which will be the display name used on the I/O Docs page
    Your completed I/O Docs definition should like the following example: 
    {
  "name":"Acme API",
  "title":"Acme API",
  "description":"",
  "version":"10",
  "protocol":"rest",
  "basePath":"http://evalXXXX.api.mashery.com/acme/v1",
  "auth":{
    "key":{
      "param":"api_key",
      "location":"query"
    }
  },
  "resources":{
    "Default":{
      "methods":{
        "GetAllProducts":{
          "description":"Get all products",
          "httpMethod":"GET",
          "path":"/product",
          "parameters":{
            "exampleParameter":{
              "description":"",
              "default":"",
              "required":false,
              "location":"query"
            }
          }
        }
      }
    }
  }
}
  4. Click Create to save the changes.