starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[Feature] Include Headscale version in Swagger API Documentation #898

New Issue
Closed
opened 2025-12-29 02:25:34 +01:00 by adam · 3 comments
adam commented 2025-12-29 02:25:34 +01:00
Owner
Copy Link

Originally created by @tale on GitHub (Jan 7, 2025).

Use case

As an implementer of a web UI for Headscale, it's hard to determine the version of Headscale that I'm interacting with via the API. For example, the 0.24 changes in the user API are hard for me to support directly (while also retaining support for 0.23) because the only "ergonomic" way to determine if a user is using Headscale 0.24 is by checking both the old and new API routes.

I am aware that I could simply just read the Swagger spec itself to track API changes, but I still think it's beneficial to retrieve the Headscale version via the API anyways.

Description

Currently the <public_url>/swagger/v1/openapiv2.json says "version not set" for the version field instead of showing a Headscale version. Based on the user-case above it would be more useful to include this version so that API implementers/consumers can read what version of Headscale is supported.

The only change would be the info.version field in gen/swagger/v1/openapiv2.json. You could also do it for the other JSON files, but I don't believe that's necessary for the actual gen process.

Contribution

  • I can write the design doc for this feature
  • I can contribute this feature

How can it be implemented?

Unsure exactly how to proceed but either the version could be generated based off of the source and stored in the source-tree or it could be set at build time based on the version via git tags.

Originally created by @tale on GitHub (Jan 7, 2025). ### Use case As an implementer of a web UI for Headscale, it's hard to determine the version of Headscale that I'm interacting with via the API. For example, the 0.24 changes in the user API are hard for me to support directly *(while also retaining support for 0.23)* because the only "ergonomic" way to determine if a user is using Headscale 0.24 is by checking both the old and new API routes. I am aware that I could simply just read the Swagger spec itself to track API changes, but I still think it's beneficial to retrieve the Headscale version via the API anyways. ### Description Currently the `<public_url>/swagger/v1/openapiv2.json` says "version not set" for the version field instead of showing a Headscale version. Based on the user-case above it would be more useful to include this version so that API implementers/consumers can read what version of Headscale is supported. The only change would be the `info.version` field in [gen/swagger/v1/openapiv2.json](https://github.com/juanfont/headscale/blob/main/gen/openapiv2/headscale/v1/headscale.swagger.json). You could also do it for the other JSON files, but I don't believe that's necessary for the actual gen process. ### Contribution - [ ] I can write the design doc for this feature - [X] I can contribute this feature ### How can it be implemented? Unsure exactly how to proceed but either the version could be generated based off of the source and stored in the source-tree or it could be set at build time based on the version via git tags.
adam added the enhancementstale labels 2025-12-29 02:25:34 +01:00
adam closed this issue 2025-12-29 02:25:34 +01:00
adam commented 2025-12-29 02:25:35 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Jan 7, 2025):

Sounds reasonable, can you see if you can make the generator include it?

@kradalby commented on GitHub (Jan 7, 2025): Sounds reasonable, can you see if you can make the generator include it?
adam commented 2025-12-29 02:25:35 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Apr 8, 2025):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Apr 8, 2025): This issue is stale because it has been open for 90 days with no activity.
adam commented 2025-12-29 02:25:35 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Apr 15, 2025):

This issue was closed because it has been inactive for 14 days since being marked as stale.

@github-actions[bot] commented on GitHub (Apr 15, 2025): This issue was closed because it has been inactive for 14 days since being marked as stale.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement stale
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#898
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?