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

1. 
   scott-weeden commented at 11:04 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. Test initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912) #32726 69ed028a1f
5. Test initial OpenAPI/Swagger specification for Bitcoin Core RPC and REST interfaces (issue #29912)

   This fixes unit tests for rpc-openapi

   9a11ec4e01
6. 
   DrahtBot commented at 11:04 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/32728.

   Reviews

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

7. 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
8. DrahtBot added the label CI failed on Jun 11, 2025
9. 
   DrahtBot commented at 11:08 am on June 11, 2025: contributor

   🚧 At least one of the CI tasks failed. Task no wallet, libbitcoinkernel: https://github.com/bitcoin/bitcoin/runs/43882810988 LLM reason (✨ experimental): The CI failure is caused by a missing ‘openapi-generator’ executable during the openapi_codegen_vs_rpc_headers test.

   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.

10. 
    willcl-ark commented at 11:12 am on June 11, 2025: member

    I strongly suspect this PR description is AI-generated; this makes it seem likely to me that the code is also AI-generated.

    I also don’t think this PR is ready for review, and it should be marked as draft (or probably better still, closed) while you work on it, at which point it can be opened.

    FYI you can run tests locally while you work on your changes. Once you have those passing it can be opened here and run against the full CI suite.

11. 
    scott-weeden commented at 12:32 pm on June 11, 2025: none

    The description of the pull request is an AI summary of the issue, the code is not. I did not have the test case properly wired in with the rest, I will close this pull request and make sure class TestOpenAPICodegen(unittest.TestCase) is running correctly.

    Also the build/test dependency can be easily installed with npm but I’m not sure the CI build process has it available.

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

    ---

Contributors
scott-weeden DrahtBot willcl-ark

Labels
CI failed