DeepSeek Harness (DSH) adopts a plugin-based architecture, aiming to address pain points in specific development scenarios through modular tools. During API interface maintenance and invocation, keeping interface definitions (OpenAPI specifications) consistent with client code and promptly identifying breaking changes introduced by version upgrades are common issues developers face. The dsh-api-contract plugin is designed for this purpose: it can parse specifications locally and generate typed client code.

Plugin Positioning and Basic Information

This is a workflow plugin maintained by uckkk under the MIT open source license. It is a pure Node implementation and does not depend on the network or external services.

Core capabilities include:
* Parsing OpenAPI 3.x specifications (JSON or YAML supported).
* Generating a typed TypeScript client (based on fetch).
* Generating a typed Python client (based on requests).
* Detecting breaking changes, including deleted API paths/methods, deleted required parameters, parameter type changes, response structure changes, and so on.

Installation and Activation

Install it using the official plugin command:

dsh plugin add github:uckkk/dsh-api-contract

After installation, you need to add the plugin to the dsh.profile.bundles list in the project’s package.json configuration file to make it available in sessions:

{
  "dsh": {
    "profile": {
      "bundles": ["dsh-api-contract"]
    }
  }
}

Typical Usage

After installation and activation, you can call the tools provided by the plugin directly in a DSH session.

1. Generate a Typed Client
Generate client code from the specified OpenAPI specification file. The following command generates a TypeScript client:

gen_client(spec="openapi.yaml", lang="typescript", outDir="./src/api")

2. Detect Breaking Changes
Before upgrading the API specification version, compare the old and new specifications to identify potential breaking changes. The following command compares two versions:

diff_spec(oldSpec="openapi.v1.", newSpec="openapi.v2.")

Applicable Scenarios and Precautions

  • Tech stack: The TypeScript client uses the browser-native fetch API directly; the Python client depends on the requests library, which must be installed before use (pip install requests).
  • Source code security: The plugin runs third-party code on the local machine with the permissions of the current DSH process. Be sure to review its source code before installation and confirm that there are no security risks before use.
  • Format support: Supports JSON and common block-based YAML (including nested mappings, sequences, and $ref references).

Summary

dsh-api-contract provides the DSH environment with a complete API contract management solution. By parsing OpenAPI specifications, generating typed clients, and auditing breaking changes, it can reduce errors caused by manual maintenance and improve the standardization of API interactions.

Related Links
* GitHub repository
* Community catalog