开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

API Documentation Test Tool

The API documentation test tool makes it easy to validate that the Markdown-based API documentation matches a REST service implementation.

The toolset includes a command line and GUI application that can be used to perform for the following validations:

• Check for broken links in the documentation.
• Print resource and method definitions.
• Verify that the documentation is internally consistent:
  • Check that defined resources and APIs that return these resources match.
  • Check that example API responses are consistent with the resources they should return.
• Verify that a target REST service matches the API documentation:
  • Check that requests and responses in the documentation match the service.
  • Inject parameters into the API calls to the service.
• Publish documentation to an output folder.

Building

To build the project, invoke either msbuild or xbuild depending on your platform. This tool is compatible with Mono or .NET.

Note: After cloning and prior to the first build, make sure to run the two commands git submodule init and git submodule update to fetch all the data from the markdowndeep submodule.

Command Line Tool

apidocs.exe [command] [options]

Available commands are:

• print - Print files, resources, and methods discovered in the documentation.
• check-links - Verify that links in the documentation aren't broken.
• check-docs - Check for errors in the documentation's resources, requests, and response examples.
• check-service - Check for differences between the documentation and service responses to documented requests.
• publish - Publish the documentation into one of the supported output formats.

All commands have the following options available:

Print Command

Print information about the source files, resources, methods, and requests that were parsed by the tool.

One of these three arguments is required to use the print command.

Check-links Command

Check for broken links in the documentation.

No specific options are required. Using --verbose will include warnings about links that were not verified.

Example: apidocs.exe check-links --path ~/github/api-docs --method search

Check-docs Command

The check-docs command ensures that the documentation is internally consistent. It verifies that:

• The JSON examples are proper JSON
• The API methods that accept or return a specific resource type have valid request/response examples
• The metadata in the documentation is formatted properly

Example: apidocs.exe check-docs --path ~/github/api-docs --method search

Check-service Command

Check the documented requests and responses against an actual REST service. This option will load accounts from a configuration file (see below), environment variables or use the specified access-token and url parameters to determine how to make API calls with the target service.

Any scenario files that are contained within the documentation path will automatically be loaded and used by the check-service method.

Example:

apidocs check-service --method "search" --access-token "foo" --url https://example.org/v1.0
apidocs check-service --headers "If-Match: *|Application: apidocs-test-app" --odata-metadata "odata.metadata=none"

Account configuration file

You can specify account information in a configuration file stored inside the documentation set. Apidocs will look for any .json file that includes an accounts property include an array of account objects. These accounts will be used by the check-service command.

See more details about account configuration files..

Account by environment variables

Instead of using an access token on the command line or an account configuration file you can use the following environment variables to provide a refresh token and token service to generate access tokens. This enables the tool to be used in automation scripts and other scenarios where it may not be possible to provide an access-token in any other way.

If these environment variables are set, it is not necessary to pass an access token using the --access-token command line parameter. The tool will call the token service to retrieve an access token when necessary.

Publish Command

The publish command uses the documentation to generate a new set of outputs.

See the documentation on publishing using APIDocs for more details.

Documentation format

See Markdown requirements for more details about requirements on the markdown source for documentation.

Request parameters

The tool also supports defining parameters for requests in a separate file. This information is loaded and used to make one or more requests to the service by substituting values for placeholders in the initial request.

For example, in a request for an item with a particular ID, you might write the request to look like this:

<!-- { "blockType": "request"; "name": "get-drive" } -->
GET /drives/{drive-id}

However, when the test tool makes the API call to the service, calling it verbatim would result in an error. Request parameters allow you to define one or more scenarios that are used to call the method.

A scenario can have one or more statically defined properties. It can also include an HTTP request and substitute one or more placeholder values with data from the response to that request.

The scenario file contains a single JSON array, with each member of the array conforming to this schema:

{
  "name": "Copy test_copy_file to a new location",
  "method": "copy-item",
  "enabled": true,
  "test-setup": [
    {
      "method": "upload-via-put",
      "http-request": "PUT /drive/root:/test_copy_file.txt:/content\r\nContent-Type: application/octet-stream\r\n\r\nTest file that we will copy to another location",
      "request-parameters":
      {
        "{path-to-file}": "/test_copy.file.txt",
        "!body": "Test file that we will copy to another location",
        "Content-Type:": "application/octet-stream"
      },
      "allowed-status-codes": [ 200 ],
      "capture": {
         "[source-file-id]": "$.id",
         "[response-type]": "Content-Type:",
         "[response-body]": "!body"
         }
    }
  ],
  "request-parameters":
  {
    "{item-id}": "[source-file-id]"
  },
  "expectations":
  {
	"$.size": 123,
	"content-type:" "application/json",
	"$.id": ["12345", "67890"]
  }
}

Test setup

The test-setup property allows you to define an array of calls that are made before the actual test method is executed. This allows you to pull values from other requests and store them to be used in the test method call. This also allows you to chain together multiple calls from the documentation to enable testing complex scenarios, like fragment uploads.

Each object in the array of test-setup is a PlaceholderRequest instance.

Canned Requests

Canned requests look just like a test setup method, but instead of being a scenario for a particular method are avaialble to be used from any scenario definition.

{
  "canned-requests": [
    {
      "name": "create-photo-item",
      "method": "upload-via-put",
      "request-parameters": {
        "{item-path}": "!random-filename-png",
        "!body.base64": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
      },
      "capture": {
        "[item-id]": "$.id"
      }
    }
  ]
}

Placeholder grammar

When specifying a placeholder name or value, the following syntax is used:

Capture grammar

The key of anything in the capture node MUST be wrapped in square brackets [foobar]. Otherwise the parameters will not be considered value.

The output-value grammar follows the same syntax as the placeholder grammar:

Code block annotation properties

The HTML-comment enclosed JSON object inside the documentation has the following properties defined:

{
	"blockType": "unknown | resource | request | response | ignored | example | simulatedResponse",
	"@odata.type": "resource name",
	"optionalProperties": [ "prop1", "prop2" ],
	"isCollection": false,
	"collectionProperty": "value",
	"isEmpty": false,
	"truncated": true,
	"name": "string name",
	"expectError": false,
	"nullableProperties": [ "prop3", "prop4" ]
}

Property descriptions

Block types

Open Source

See OpenSourceNotes for more details about open source usage in markdown-scanner.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.