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

Most developers are comfortable with Markdown, enjoy being able to work in their existing text editor or IDE (integrated development environment) to edit content, prefer to collaborate in a Git repo using branching, merging, and code review tools, and are generally comfortable with the whole code-based process and environment. Apidoc-markdown2 -p examples -o examples/example.md View generated example. Why apidoc-markdown2. Apidoc-markdown is not maintained for long time. New tags of apidoc are not supported. This version is applied pull request for supporting new tags.

The toolset includes a command line and GUI application that can be used toperform 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 dotnet build. The tool has been upgraded to use dotnet core.

Command Line Tool

apidoc.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 requeststhat 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 aboutlinks that were not verified.

Example: apidoc.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: apidoc.exe check-docs --path ~/github/api-docs --method search

Check-service Command

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

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

Example:

Account configuration file

You can specify account information in a configuration file stored inside thedocumentation set. Apidoc will look for any .json file that includes anaccounts property include an array of account objects. These accounts willbe 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 fileyou can use the following environment variables to provide a refresh token andtoken service to generate access tokens. This enables the tool to be used inautomation scripts and other scenarios where it may not be possible to providean access-token in any other way.

If these environment variables are set, it is not necessary to pass an accesstoken using the --access-token command line parameter. The tool will call thetoken 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 API Doctor formore details.

Documentation format

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

Request parameters

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

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

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

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

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

Test setup

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

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

Apidoc Markdown Manager

Canned Requests

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

Placeholder grammar

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

Apidoc Markdown Problems

Capture grammar

The key of anything in the capture node MUST be wrapped in squarebrackets [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 followingproperties defined:

Property descriptions

Block types

| Name | Description ||:——————–|:————————————————————————————————————————————-|| resource | The json block describes a system resource (complex type) in the API. || request | The json block describes an HTTP request that can be made by clients. || response | The json block describes the HTTP response that is sent from the service. || example | An example of the JSON data that would be generated by the client or returned by the service, without being wrapped in an HTTP call. || simulatedResponse | Used for unit testing to simulate responses from the service. || ignored | No processing is done on the code block that follows. |

Open Source

See OpenSourceNotes for more details about open source usage in API Doctor.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Api Doc Markdown Example

Released:

Modular documentation generator for rest framwork apis

Project description

Release historyRelease notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Hashes for djangorestframework-apidoc-0.0.1.tar.gz