{"id":20054311,"url":"https://github.com/onedrive/apidoctor","last_synced_at":"2025-04-12T22:28:46.736Z","repository":{"id":33584478,"uuid":"136665646","full_name":"OneDrive/apidoctor","owner":"OneDrive","description":"Application for validating API documentation and generating test cases","archived":false,"fork":false,"pushed_at":"2025-03-18T02:02:41.000Z","size":3211,"stargazers_count":41,"open_issues_count":7,"forks_count":24,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-04T01:41:23.167Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneDrive.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-08T21:00:49.000Z","updated_at":"2025-01-02T06:15:13.000Z","dependencies_parsed_at":"2024-01-12T10:28:15.927Z","dependency_job_id":"2329f299-135e-4e4e-86fb-d6883d082532","html_url":"https://github.com/OneDrive/apidoctor","commit_stats":{"total_commits":692,"total_committers":25,"mean_commits":27.68,"dds":0.4653179190751445,"last_synced_commit":"92c30894b7391e97a34510e15cd573c6a9e61fbd"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDrive%2Fapidoctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDrive%2Fapidoctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDrive%2Fapidoctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDrive%2Fapidoctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneDrive","download_url":"https://codeload.github.com/OneDrive/apidoctor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248639293,"owners_count":21137819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T12:39:46.437Z","updated_at":"2025-04-12T22:28:46.713Z","avatar_url":"https://github.com/OneDrive.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![API Doctor](ApiDoctor-300.png)\n\n[![Build status](https://ci.appveyor.com/api/projects/status/0k9g6q2radu3xv2l/branch/master?svg=true)](https://ci.appveyor.com/project/OneDrive/apidoctor/branch/master)\n\nThe API Doctor documentation test tool makes it easy to validate that the Markdown-based API\ndocumentation matches a REST service implementation.\n\nThe toolset includes a command line and GUI application that can be used to\nperform for the following validations:\n\n* Check for broken links in the documentation.\n* Print resource and method definitions.\n* Verify that the documentation is internally consistent:\n  * Check that defined resources and APIs that return these resources match.\n  * Check that example API responses are consistent with the resources they should return.\n* Verify that a target REST service matches the API documentation:\n  * Check that requests and responses in the documentation match the service.\n  * Inject parameters into the API calls to the service.\n* Publish documentation to an output folder.\n\n## Building\nTo build the project, invoke `dotnet build`. The tool has been upgraded to use dotnet core.\n\n## Command Line Tool\n\n![Screen shot of the command line tool in action](example-console.png)\n\n`apidoc.exe [command] [options]`\n\nAvailable commands are:\n\n* `print` - Print files, resources, and methods discovered in the documentation.\n* `check-links` - Verify that links in the documentation aren't broken.\n* `check-docs` - Check for errors in the documentation's resources, requests, and response examples.\n* `check-service` - Check for differences between the documentation and service responses to documented requests.\n* `publish` - Publish the documentation into one of the supported output formats.\n\nAll commands have the following options available:\n\n| Option             | Description                                                                                 |\n|:-------------------|:--------------------------------------------------------------------------------------------|\n| `--path \u003cpath\u003e`    | Path to the root of the documentation set to scan. If missing, the current path is assumed. |\n| `--short`          | Print concise output to the console.                                                        |\n| `--verbose`        | Print verbose output to the console, including full HTTP requests/responses.                |\n| `--log \u003clog_file\u003e` | Log console output to a file.                                                               |\n| `--parameters \u003cparams\u003e` | A URL-encoded string containing key/value pairs. Allows additional parameters to be passed to the task. Currently used by the tagging feature to specify content to include. For more information see [Markdown customizations](docs/markdown-customizations.md). |\n\n### Print Command\nPrint information about the source files, resources, methods, and requests\nthat were parsed by the tool.\n\n| Option        | Description                                                       |\n|:--------------|:------------------------------------------------------------------|\n| `--files`     | Output information about the files contained in the document set. |\n| `--resources` | Output resource definitions read from the documentation.          |\n| `--methods`   | Output method definitions read from the documentation.            |\n\nOne of these three arguments is required to use the `print` command.\n\n### Check-links Command\nCheck for broken links in the documentation.\n\nNo specific options are required. Using `--verbose` will include warnings about\nlinks that were not verified.\n\nExample: `apidoc.exe check-links --path ~/github/api-docs --method search`\n\n### Check-docs Command\nThe `check-docs` command ensures that the documentation is internally consistent.\nIt verifies that:\n\n* The JSON examples are proper JSON\n* The API methods that accept or return a specific resource type have valid request/response examples\n* The metadata in the documentation is formatted properly\n\n| Option                   | Description                                                                                        |\n|:-------------------------|:---------------------------------------------------------------------------------------------------|\n| `--method \u003cmethod_name\u003e` | Optional. Specify the name of a request method to evaluate. If missing, all methods are evaluated. |\n\nExample: `apidoc.exe check-docs --path ~/github/api-docs --method search`\n\n### Check-service Command\n\nCheck the documented requests and responses against an actual REST service. This\noption will load accounts from a configuration file (see below), environment\nvariables or use the specified access-token and url parameters to determine\nhow to make API calls with the target service.\n\nAny scenario files that are contained within the documentation path will\nautomatically be loaded and used by the check-service method.\n\n| Option                     | Description                                                                                                                                                                             |\n|:---------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `--access-token \"token\"`   | OAuth access token to use when calling the service. You may need to escape the token value by enclosing it in double quotes.                                                            |\n| `--branch-name \u003cbranch\u003e`   | Optional. Specify the branch name that is the source of the documentation. Compares this name to the configuration file to see if the check-service command is allowed for this branch. |\n| `--headers \u003cheaders\u003e`      | Optional. Enables adding additional headers to every API call made by check-service. The format should be a quoted string with a | separating different header lines.                   |\n| `--ignore-scopes`          | Optional. Disables using scopes to determine which methods are exercised on an account. |\n| `--method \u003cmethod_name\u003e`   | Optional. Check a single request/response method instead of everything in the documentation.                                                                                            |\n| `--odata-metadata \u003cvalue\u003e` | Optional. Specify the value of the odata.metadata level that is provided in the Accept header.                                                                                          |\n| `--pause`                  | Pause for a key press between API calls to the service to enable reading the responses.                                                                                                 |\n| `--scopes \u003cscopes\u003e`        | Provide a command separated list of scopes which are provided by the command line accessToken. |\n| `--url \u003curl\u003e`              | Set the base URL for the service calls.                                                                                                                                                 |\n\nExample:\n```\napidoc check-service --method \"search\" --access-token \"foo\" --url https://example.org/v1.0\napidoc check-service --headers \"If-Match: *|Application: apidoc-test-app\" --odata-metadata \"odata.metadata=none\"\n```\n\n#### Account configuration file\nYou can specify account information in a configuration file stored inside the\ndocumentation set. Apidoc will look for any .json file that includes an\n`accounts` property include an array of account objects. These accounts will\nbe used by the `check-service` command.\n\n[See more details about account configuration files.](docs/account-configuration.md).\n\n\n#### Account by environment variables\n\nInstead of using an access token on the command line or an account configuration file\nyou can use the following environment variables to provide a refresh token and\ntoken service to generate access tokens. This enables the tool to be used in\nautomation scripts and other scenarios where it may not be possible to provide\nan access-token in any other way.\n\n| Variable name           | Description                                                                |\n|:------------------------|:---------------------------------------------------------------------------|\n| **oauth-token-service** | URL for the OAuth 2.0 token service to be used to retrieve an access token |\n| **oauth-client-id**     | Client ID that is passed to the token service                              |\n| **oauth-client-secret** | Client Secret that is passed to the token service                          |\n| **oauth-redirect-uri**  | Redirect URI used to generate the refresh token                            |\n| **oauth-refresh-token** | Refresh token that is used to generate an access token                     |\n\nIf these environment variables are set, it is not necessary to pass an access\ntoken using the `--access-token` command line parameter. The tool will call the\ntoken service to retrieve an access token when necessary.\n\n### Publish Command\nThe `publish` command uses the documentation to generate a new set of outputs.\n\nSee the documentation on [publishing using API Doctor](docs/publishing.md) for\nmore details.\n\n## Documentation format\nSee [Markdown requirements](docs/markdown-requirements.md) for more details about\nrequirements on the markdown source for documentation.\n\n## Request parameters\n\nThe tool also supports defining parameters for requests in a separate file. This\ninformation is loaded and used to make one or more requests to the service by\nsubstituting values for placeholders in the initial request.\n\nFor example, in a request for an item with a particular ID, you might write the\nrequest to look like this:\n\n```\n\u003c!-- { \"blockType\": \"request\"; \"name\": \"get-drive\" } --\u003e\nGET /drives/{drive-id}\n```\n\nHowever, when the test tool makes the API call to the service, calling it verbatim\nwould result in an error. Request parameters allow you to define one or more\nscenarios that are used to call the method.\n\nA scenario can have one or more statically defined properties. It can also include\nan HTTP request and substitute one or more placeholder values with data from\nthe response to that request.\n\nThe scenario file contains a single JSON array, with each member of the array\nconforming to this schema:\n\n```json\n{\n  \"name\": \"Copy test_copy_file to a new location\",\n  \"method\": \"copy-item\",\n  \"enabled\": true,\n  \"test-setup\": [\n    {\n      \"method\": \"upload-via-put\",\n      \"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\",\n      \"request-parameters\":\n      {\n        \"{path-to-file}\": \"/test_copy.file.txt\",\n        \"!body\": \"Test file that we will copy to another location\",\n        \"Content-Type:\": \"application/octet-stream\"\n      },\n      \"allowed-status-codes\": [ 200 ],\n      \"capture\": {\n         \"[source-file-id]\": \"$.id\",\n         \"[response-type]\": \"Content-Type:\",\n         \"[response-body]\": \"!body\"\n         }\n    }\n  ],\n  \"request-parameters\":\n  {\n    \"{item-id}\": \"[source-file-id]\"\n  },\n  \"expectations\":\n  {\n\t\"$.size\": 123,\n\t\"content-type:\" \"application/json\",\n\t\"$.id\": [\"12345\", \"67890\"]\n  }\n}\n```\n\n| Property             | Type            | Description                                                                                                                                     |\n|:---------------------|:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------|\n| `name`               | string          | The name of the scenario described.                                                                                                             |\n| `method`             | string          | The name of the method this scenario uses. Either defined in the documentation or a substitute name is auto-generated.                          |\n| `enabled`            | bool            | Enable or disable the scenario.                                                                                                                 |\n| `test-setup`         | array           | See below.                                                                                                                                      |\n| `request-parameters` | key-value pairs | Specify the key-value pairs for parameters for the request. The key is used as a placeholder name, and the value is subed into the placeholder. |\n| `expectations`       | key-value pairs | Specify the expected values in the final response. The keys are the same [Capture Grammar](#capture-grammer) defined for request-parameters.    |\n\n### Test setup\n\nThe test-setup property allows you to define an array of calls that are made\nbefore the actual test method is executed. This allows you to pull values from\nother requests and store them to be used in the test method call. This also\nallows you to chain together multiple calls from the documentation to enable\ntesting complex scenarios, like fragment uploads.\n\nEach object in the array of `test-setup` is a `PlaceholderRequest` instance.\n\n| Property               | Type            | Description                                                                                                                                                                                                   |\n|:-----------------------|:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `method`               | string          | The name of a method from the documentation that should be used as this test-setup call                                                                                                                       |\n| `http-request`         | string          | Instead of specifying a method from the docs, you can input a raw HTTP request to be used.                                                                                                                    |\n| `request-parameters`   | key-value pairs | Specify the key-value pairs for parameters for the request. The key is used as a placeholder name, and the value is subed into the placeholder.                                                               |\n| `allowed-status-codes` | array of int    | Normally the request is considered failed of the response is anything other than 2xx. Use this to allow error codes and other responses to be considered valid.                                               |\n| `capture`              | key-value pairs | Specify the key-value pairs of values that are read from this response and stored for another request under this scenario. Allows you to store values and use them in other requests under the same scenario. |\n| `canned-request`       | string          | The name of the canned-request defined in the scenario file that is executed. This way common requests can be stored in one place instead of repeated throughtout the test files.                             |\n\n\n### Canned Requests\nCanned requests look just like a test setup method, but instead of being a\nscenario for a particular method are avaialble to be used from any scenario\ndefinition.\n\n```json\n{\n  \"canned-requests\": [\n    {\n      \"name\": \"create-photo-item\",\n      \"method\": \"upload-via-put\",\n      \"request-parameters\": {\n        \"{item-path}\": \"!random-filename-png\",\n        \"!body.base64\": \"iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==\"\n      },\n      \"capture\": {\n        \"[item-id]\": \"$.id\"\n      }\n    }\n  ]\n}\n```\n\n\n\n\n### Placeholder grammar\n\nWhen specifying a placeholder name or value, the following syntax is used:\n\n| Syntax          | Example                | Description                                                                                                                               |\n|:----------------|:-----------------------|:------------------------------------------------------------------------------------------------------------------------------------------|\n| Curly Braces    | `{path-to-file}`       | Find and update a value in the URL matching the full string.                                                                              |\n| Square Braces   | `[source-file-id]`     | Look for a previous stored value that was output from a previous request within the same scenario.                                        |\n| JPath           | `$.id`                 | Replace a property value in the JSON body of the request. If the content-type of the request is not application/json an error will occur. |\n| !body           | `!body`                | Replace the content stream of the request with the provided value                                                                         |\n| !body.base64    | `!body.base64`         | Replace the content stream of the request with a decoded byte stream of the base 64 value provided.                                       |\n| !url            | `!url`                 | Replace the URL for the request with the provided value.                                                                                  |\n| Header:         | `Content-Type:`        | Replace the value of a header with the specified value. Note the header name must end with a colon to be valid.                           |\n| Random Filename | `!random-filename-png! | Returns a randomly generated value with a particular file extension that can be used to ensure tests don't interfere with each other.     |\n\n### Capture grammar\n\nThe `key` of anything in the `capture` node MUST be wrapped in square\nbrackets `[foobar]`. Otherwise the parameters will not be considered value.\n\nThe output-value grammar follows the same syntax as the placeholder grammar:\n\n| Syntax  | Example         | Description                                           |\n|:--------|:----------------|:------------------------------------------------------|\n| JPath   | $.id            | Read and store the value at the JPath                 |\n| Header: | `Content-Type:` | Read and store the value of the specified HTTP header |\n| !body   | !body           | Read and store the complete body of the response      |\n\n### Code block annotation properties\n\nThe HTML-comment enclosed JSON object inside the documentation has the following\nproperties defined:\n\n```json\n{\n\t\"blockType\": \"unknown | resource | request | response | ignored | example | simulatedResponse\",\n\t\"@odata.type\": \"resource name\",\n\t\"optionalProperties\": [ \"prop1\", \"prop2\" ],\n\t\"isCollection\": false,\n\t\"collectionProperty\": \"value\",\n\t\"isEmpty\": false,\n\t\"truncated\": true,\n\t\"name\": \"string name\",\n\t\"expectError\": false,\n\t\"nullableProperties\": [ \"prop3\", \"prop4\" ]\n}\n```\n\n#### Property descriptions\n\n| Name                   | Value            | Allowed blocks                       | Description                                                                                                                                                                                                     |\n|:-----------------------|:-----------------|:-------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **blockType**          | string           | All                                  | Describes the type of the json block proceeding the annotation.                                                                                                                                                 |\n| **@odata.type**        | string           | All                                  | Describes the name of the resource (either being defined, in the case of a resource block, or as the body type on a request/response block)                                                                     |\n| **optionalProperties** | array of strings | resource                             | An array of properties that are not required to be in the code block.                                                                                                                                           |\n| **isCollection**       | boolean          | response, example, simulatedResponse | Indicates that the block contains a collection of items that match the **@odata.type** schema. This is expected as an object with a single property that is an array of objects.                                |\n| **collectionProperty** | string           | response, example, simulatedResponse | Provides the name of the variable that contains the collection. Default value: `value`.                                                                                                                         |\n| **isEmpty**            | boolean          | response, example, simulatedResponse | Indicates that the collection value is expected to be empty (or not).                                                                                                                                           |\n| **truncated**          | boolean          | response, example, simulatedResponse | Indicates that the block will not include all properties of the resource and that's not an error. Properties explicitly shown in the code block are always considered required when tested against the service. |\n| **name**               | string           | request, example                     | Provides the name of the request method being defined.                                                                                                                                                          |\n| **expectError**        | boolean          | response, example, simulatedResponse | Use this to indicate that instead of returning the normal response as defined, an error response will be returned.                                                                                              |\n| **nullableProperties** | array of strings | response, example, simulatedResponse | Provide a list of properties that are allowed to have null values. By default, null values for a property will generate a warning.                                                                              |\n\n\n#### Block types\n| Name                | Description                                                                                                                          |\n|:--------------------|:-------------------------------------------------------------------------------------------------------------------------------------|\n| `resource`          | The json block describes a system resource (complex type) in the API.                                                                |\n| `request`           | The json block describes an HTTP request that can be made by clients.                                                                |\n| `response`          | The json block describes the HTTP response that is sent from the service.                                                            |\n| `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. |\n| `simulatedResponse` | Used for unit testing to simulate responses from the service.                                                                        |\n| `ignored`           | No processing is done on the code block that follows.                                                                                |\n\n\n## Open Source\n\nSee [OpenSourceNotes](OpenSourceNotes.md) for more details about open source usage in API Doctor.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonedrive%2Fapidoctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonedrive%2Fapidoctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonedrive%2Fapidoctor/lists"}