Skip to main content

API Document Management and API Test

Overview​

Properly managing API documentation is crucial for developer onboarding, testing, and integration. APIM allows you to attach OpenAPI specs or manually define documentation, then test APIs immediately within the interface. This tutorial shows how to upload/edit documentation and run tests for a deployed API using sample configurations.

Prerequisites​

You’ll need:

  • A deployed API version (e.g., user-service-api v1.0)
  • Access to APIM Console with Editor or Administrator permissions
  • OpenAPI spec file or API definition details if writing manually

Step-by-Step Tutorial​

Step 1. Open API Version Detail Page​

  • Go to API Management
  • Select user-service-api
  • Select version v1.0

Step 2. Upload or Edit API Documentation​

You have two options:

Option A: Upload OpenAPI (YAML/JSON)

  • Click Import
  • Select and upload your OpenAPI 3.0 file (e.g., user-service-v1.yaml)
  • The system parses and updates all endpoints and descriptions

Option B: Manual API Definition

If no OpenAPI file is available:

  • Click Edit under the Documentation tab
  • Add details manually: | Field | Example | | --- | --- | | Summary | User login endpoint | | Method | POST | | Path | /login | | Request Body | JSON with username, password | | Response | 200 OK + JSON body |

Click Save when done.

Step 3. Test the API Using Built-In Tester​

Navigate to the Test tab in the API version detail page:

FieldValue
Target MethodPOST
Path/v1/login
HeadersContent-Type: application/json

Body example:

{
"username": "jane.doe",
"password": "test1234"
}

Click Send Request

Step 4. Review the Test Results​

Expected Response:

{
"userId": "12345",
"token": "eyJhbGciOi..."
}

The console will show:

  • HTTP status code (e.g., 200 OK)
  • Time taken
  • Request & response body

Common Issues & Troubleshooting​

IssueCauseSolution
Invalid OpenAPI fileSyntax error or unsupported fieldsValidate using Swagger Editor
No response in testWrong path or missing backendDouble-check Gateway route path and backend health
401 UnauthorizedAPI key or auth policy missingSet Authorization header or disable auth temporarily
415 Unsupported Media TypeMissing or wrong Content-TypeUse application/json for body requests

Best Practices​

  • Always upload a validated OpenAPI spec for accurate documentation
  • Add example requests/responses for every endpoint
  • Use built-in tester before sharing API with external consumers
  • Document error responses (4xx/5xx), not just success cases
  • Keep API docs versioned with API lifecycle