Documentation and Inspector
Documentation refers to the specifications and manifests you use for testing and analysis. You can upload the documentation and use it in Conformance Analysis or API Security Testing (AST) Scans according to your requirements. Traceable supports the following types of API documentation:
Open API Specification
Postman Collection
Postman Environment
GraphQL Schema
WSDL
MCP Server
You can use either of the above types and upload one or more files according to your requirements. For more information on uploading files, see Uploading Documentation.
While uploading an API documentation, Traceable also provides you with the option to enable:
Naming (OpenAPI documentation type only) — This option is useful when you want Traceable to use the specification for API naming.
Inspector (OpenAPI documentation type only) — This option is useful when you want Traceable to run the specification analyzer on your uploaded files.
Discovery (OpenAPI, WSDL, and MCP Server documentation types only) — This option is useful when you want Traceable to discover APIs or MCP assets from the uploaded specification.
For instructions on enabling these options, refer to the section below.
Uploading Documentation
Navigate to the Discovery → API Documentation tab, and click Upload in the page’s top right corner to start uploading API documentation.
As part of uploading the documentation, complete the following:
Documentation Name — The name of the documentation. This field is non-editable as Traceable uses the uploaded specification name as the documentation name.
Documentation Type — The type of documentation you wish to upload. For example, Open API Spec. For information on the MCP server manifest format, see Sample MCP Server manifest format
Enabled for Naming — If enabled, the toggle allows Traceable to rename API endpoints according to the uploaded specification. For more information on API naming rules, see API naming.
Run Inspector — If enabled, the toggle allows Traceable to analyze the uploaded specification for security concerns. For more information, see API Inspector.
Enable Discovery — If enabled, the toggle allows the discovery of assets (API and MCP server-related) based on the specification(s) you upload. Traceable lists the discovered assets on the Inventory page, using the documentation type as the source. For more information, see Inventory.
Upload Documentation — The documentation you wish to upload. You can upload a single file or a folder containing multiple files. Post-upload, you can update the file name and path according to your requirements. For information on the MCP manifest format, see Sample MCP server manifest format.
Traceable uses this file name as the documentation name. Following is the folder structure used in the above demo:
Once you have configured the above, click Save. Traceable displays the uploaded documentation as shown in the image below.
Sample MCP server manifest format
The following is the format that you can use to upload the MCP server manifest:
Documentation detailed view
After you upload documentation, click the document to view its details. Upon clicking, Traceable displays the following details based on the uploaded documentation type.
Reference Tree — The main specification file (parent specification) from the directory or folder you upload may contain one or more references, either nested or standalone. The tree visually represents these references, helping you navigate the connections between them. For example, in the above image,
openapi.yamlis the main specification above and contains references toorders.yaml,customers.yaml, andproducts.yamlfiles. Similarly,orders.yamlandcustomers.yamlcontain references tocustomers.yamlandaddress.yamlfiles respectively, whileproducts.yamldoes not contain any references. The reference tree visually illustrates how different API specifications are linked together. This makes it easy to see the structure and resolve missing references quickly. For more information, see API Referencing.API Spec/MCP Server — This section provides a detailed view of the specification or manifest. This is the resolved specification or manifest, meaning that Traceable resolves all references across the files that you uploaded. For example, the
openapi.yamlfile shown above contains references toorders.yaml,customers.yaml, andproducts.yamlfiles. However, those references are not visible in the image above because Traceable replaced them with the content in the files.Paths found in OpenAPI spec — This section lists all the paths Traceable discovers as part of the uploaded OpenAPI specification. If you enabled the API inspector while uploading the document, the section shows the issues found and the API inspector score corresponding to each path. For example, in the above image, the
/v1/customers/{customerid}path contains 3 issues and an API inspector score of 68. Similarly, this information is shown for all paths within an API documentation. For more information on the issues and score, see API Inspector.
Specification uploads limits
Maximum file size: 100 MB
Maximum number of files: 100
You can upload individual files or an entire folder. Traceable processes all files included in the upload.
API Referencing
If you upload a directory or multiple specifications, Traceable goes through the main specification file (parent spec) and searches for references ($ref). Based on the files you upload, Traceable resolves the paths with their respective files. Based on these references, Traceable creates a reference tree that is visible when you edit any existing documentation or in the documentation detailed view, as shown below.
Traceable highlights the unresolved references with a red dot at the top right of the file or folder on the API Documentation page, for example, paths.yaml folder in the above image. This mainly occurs when the file is missing. At that time, you can edit the API document and do either of the following in the Reference Tree section:
Click the Upload icon and upload the missing documentation.
Click the missing document field and select an existing one from the drop-down.
Traceable tries to resolve the references based on the above documents. If it is unable to do so due to issues with the documents, you can repeat the above step.
API Inspector
The API Inspector is a code analyzer of the Open API documentation that you upload. If you enable this feature, Traceable goes through the documentation and produces a result at the path level. Traceable performs these checks once a day, and as soon as you update or upload the API documentation.
The API inspector checks for issues in three areas:
Security — This category checks for potential security issues, such as weak authentication mechanisms, missing headers, inaccurate references, etc, that can expose APIs to attacks.
Format — This category verifies whether the API paths adhere to the expected structure and formatting rules outlined in the OpenAPI document, ensuring proper syntax and compliance with API standards.
Data Validation — This category verifies whether the data types and structures defined in the OpenAPI document are properly implemented, ensuring that inputs and outputs conform to the expected formats, constraints, and value ranges.
Each of the above categories has multiple checks associated with it. Traceable provides these checks out-of-the-box and executes them on each path present in the OpenAPI specification and calculates an API Inspector score. The score is calculated for each path and for the entire uploaded API documentation. The audit score ranges from 0-100, with 100 being the highest. A higher score represents better compliance.
Traceable also shows the following detailed information for each path. To view this information, navigate to the detailed view page of an API documentation, Paths found in the OpenAPI spec section, and click a path.
API Inspector score for that path
The list of checks performed on that path, along with the check name, category, description, severity, and status (fail or pass). You can also click each check to view its description and a detailed example of the possible issue. This example is context-sensitive, and you can use it to fix the issue in your uploaded document. Traceable also lists the potential vulnerabilities detected by that check.
If you fix either failed check in the OpenAPI document, Traceable runs the API inspector and updates its status accordingly.
Last updated
Was this helpful?