Add initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912) #32726

1. 
   scott-weeden commented at 9:48 am on June 11, 2025: none

   Motivation

   Currently, (almost) all clients manually implement the Bitcoin Core RPC API, which leads to:

   • Accidental implementation bugs (e.g., unit mistakes such as vB vs BTC/kvB)
   • Difficulty maintaining clients as the API evolves
   • Increased effort to implement clients in new programming languages

   There is no formal, machine-readable specification of the RPC API. Existing documentation is not sufficient for code generation or type-safe client implementations. See discussion in #29912.

   Overview

   This PR introduces an initial OpenAPI/Swagger specification for the Bitcoin Core RPC and REST interfaces. The goal is to provide a foundation for:

   • Automated client code generation in multiple languages (e.g., via Kiota)
   • Easier maintenance and improved correctness for downstream clients
   • A step towards a spec-driven development process for the RPC API

   Details

   • Adds share/openapi.yml describing the REST API (and/or bitcoin-rpc-openapi.yaml for the JSON-RPC interface).
   • The spec is based on the current implementation and documentation, but is a work in progress and will need to be updated as the API evolves.
   • See #29912 for background, rationale, and community discussion.

   Tests

   This change is documentation/specification only. No code is modified. Downstream client generators and tools can be used to validate the spec.

   Further Work

   • Extend the OpenAPI spec to cover all RPC methods and parameters, including type details and units.
   • Consider generating JSON Schema or OpenRPC specifications for even better machine-readability and codegen support.
   • Integrate with CI to ensure the spec remains up-to-date.

   ---

   Closes #29912

   ---

2. RFC: Formal description of the RPC API. See #29912 d539257d4a
3. Merge branch 'master' of https://github.com/bitcoin/bitcoin 0bae97887d
4. 
   DrahtBot commented at 9:48 am on June 11, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32726.

   Reviews

   See the guideline for information on the review process. A summary of reviews will appear here.

   LLM Linter (✨ experimental)

   Possible typos and grammar issues:

   • infos -> information [“infos” is not a valid plural; use “information” for comprehension]

   drahtbot_id_4_m

5. DrahtBot renamed this:
   Add initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912)
   Add initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912)
   on Jun 11, 2025
6. Test initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912) #32726 69ed028a1f
7. DrahtBot added the label CI failed on Jun 11, 2025
8. 
   DrahtBot commented at 10:58 am on June 11, 2025: contributor

   🚧 At least one of the CI tasks failed. Task previous releases, depends DEBUG: https://github.com/bitcoin/bitcoin/runs/43882460633 LLM reason (✨ experimental): The CI failure is caused by compiler errors due to unrecognized command-line options during configuration.

   Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

   • Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

   • A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

   • An intermittent issue.

   Leave a comment here, if you need help tracking down a confusing failure.

9. Test initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912)

   This fixes unit tests for rpc-openapi

   9a11ec4e01
10. scott-weeden closed this on Jun 11, 2025

    ---

11. scott-weeden reopened this on Jun 11, 2025

    ---

12. scott-weeden closed this on Jun 11, 2025

    ---

Contributors
scott-weeden DrahtBot

Labels
CI failed