Openapi spec

[kalindafab]

This PR introduces an OpenAPI specification for selected REST APIs in the Jenkins Git Plugin, improving API documentation and developer accessibility.

Testing done

Added openapi/git-plugin.yaml with API definitions.
Documented key endpoints such as:

SCM Configuration: /job/{job_name}/scm/api/json
Git Tags: /job/{job_name}/git/tag/api/json
Merge Options: /job/{job_name}/scm/mergeOptions/api/json

Submitter checklist

• Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
• Ensure that the pull request title represents the desired changelog entry
• Please describe what you did
• Link to relevant issues in GitHub or Jira
• Link to relevant pull requests, esp. upstream and downstream changes
• Ensure you have provided tests - that demonstrates feature works or fixes the issue

[MarkEWaite]

@kalindafab I have some questions:

• How will this be used?
• Who will use it?
• How was it tested to confirm that the specification is correct? What failure modes were tested? What success cases were tested? What Jenkins job types were tested?
• How will it be tested in the future to assure that the specification is still implemented as described?
• Is there a place where you're envisioning that this will be published as part of a larger OpenAPI specification effort for Jenkins?

[kalindafab]

@MarkEWaite
I created this OpenAPI specification for the Git plugin as part of my GSoC 2025 proposal to demonstrate how standardized API documentation can be applied to Jenkins plugins.
The spec was generated partly at runtime and partly through manual inspection and visualization of the plugin’s REST API behavior.
I haven’t implemented automated tests yet , this is just an early proof of concept. if i’m accepted into GSoC, I plan to continue developing this over the summer and build tooling for automatic and consistent spec generation, as outlined in my proposal. If not, I still intend to keep contributing, especially to the Git plugin, since it’s widely used and I found working on it genuinely interesting.
Let me know if you’d prefer I convert this PR to a draft so it doesn’t block anything or cause confusion.

[MarkEWaite]

Thanks for the explanation. I've marked the pull request as draft.