Skip to content

Commit 98a3cc5

Browse files
committed
api: advertise bearer auth and annotate endpoint security
Switch the OpenAPI security scheme from the invalid "Token" type to a proper http/bearer definition. The auth middleware now accepts both "Bearer" and "Token" prefixes for backward compatibility. Add Security annotations to all endpoints that require authentication so that the generated docs show lock icons on protected operations. Update the RST documentation accordingly. Signed-off-by: Robin Jarry <robin@jarry.cc>
1 parent 4d17135 commit 98a3cc5

11 files changed

Lines changed: 42 additions & 5 deletions

File tree

‎docs/api/index.rst‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -122,16 +122,19 @@ a ``Content-Type`` of ``application/json``:
122122
Authentication
123123
--------------
124124

125-
Patchwork supports authentication using basic authentication (username and
126-
password) or token authentication (recommended).
125+
Patchwork supports authentication using bearer token authentication. To
126+
authenticate, first generate a token from your user profile page, then::
127127

128-
To authenticate with a token, first obtain one from your profile page, then::
128+
$ curl -H "Authorization: Bearer ${token}" \
129+
'https://patchwork.example.com/api/'
130+
131+
The legacy ``Token`` scheme is also accepted for backward compatibility::
129132

130133
$ curl -H "Authorization: Token ${token}" \
131134
'https://patchwork.example.com/api/'
132135

133136
Not all resources require authentication. Those that do will return
134-
``404 (Not Found)`` if authentication is not provided.
137+
``401 (Unauthorized)`` if authentication is not provided.
135138

136139
Pagination
137140
----------

‎pkg/api/api.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ const (
2626
maxPerPage = 250
2727
)
2828

29+
var authRequired = []map[string][]string{{"bearer": {}}}
30+
2931
type PageParams struct {
3032
Page int `query:"page" minimum:"1" default:"1" doc:"Page number"`
3133
PerPage int `query:"per_page" minimum:"1" maximum:"250" default:"30" doc:"Results per page"`
@@ -189,6 +191,15 @@ func NewRouter(cfg *config.Config, database *bun.DB, baseURL string, bus db.Even
189191
r.Use(authMiddleware(database))
190192

191193
config := huma.DefaultConfig("Patchwork API", "1.4")
194+
config.Info.Description = "REST API for the Patchwork patch tracking system."
195+
config.Components.SecuritySchemes = map[string]*huma.SecurityScheme{
196+
"bearer": {
197+
Type: "http",
198+
Scheme: "bearer",
199+
Description: "API token generated from [your user profile](/user). " +
200+
"The legacy `Token` scheme is also accepted.",
201+
},
202+
}
192203
config.DocsPath = "/api/docs"
193204
config.OpenAPIPath = "/api/openapi"
194205
config.SchemasPath = "/api/schemas"

‎pkg/api/auth.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ func authMiddleware(database *bun.DB) func(http.Handler) http.Handler {
1919
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
2020
auth := r.Header.Get("Authorization")
2121
scheme, token, _ := strings.Cut(auth, " ")
22-
if strings.EqualFold(scheme, "token") {
22+
if strings.EqualFold(scheme, "bearer") ||
23+
strings.EqualFold(scheme, "token") {
2324
token = strings.TrimSpace(token)
2425
q := db.GetQueries(r.Context())
2526
user, err := q.GetUserByToken(token)

‎pkg/api/bundles.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,22 +32,26 @@ func registerBundleRoutes(api huma.API, h *handler, prefix string, mw huma.Middl
3232
Method: http.MethodPost, Path: prefix + "/bundles",
3333
OperationID: fmt.Sprintf("create-bundle-v%s", prefix[5:]),
3434
DefaultStatus: 201,
35+
Security: authRequired,
3536
Middlewares: mw,
3637
}, h.CreateBundle)
3738
huma.Register(api, huma.Operation{
3839
Method: http.MethodPatch, Path: prefix + "/bundles/{id}",
3940
OperationID: fmt.Sprintf("update-bundle-v%s", prefix[5:]),
41+
Security: authRequired,
4042
Middlewares: mw,
4143
}, h.UpdateBundle)
4244
huma.Register(api, huma.Operation{
4345
Method: http.MethodPut, Path: prefix + "/bundles/{id}",
4446
OperationID: fmt.Sprintf("put-bundle-v%s", prefix[5:]),
47+
Security: authRequired,
4548
Middlewares: mw,
4649
}, h.UpdateBundle)
4750
huma.Register(api, huma.Operation{
4851
Method: http.MethodDelete, Path: prefix + "/bundles/{id}",
4952
OperationID: fmt.Sprintf("delete-bundle-v%s", prefix[5:]),
5053
DefaultStatus: 204,
54+
Security: authRequired,
5155
Middlewares: mw,
5256
}, h.DeleteBundle)
5357
}

‎pkg/api/checks.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,13 @@ func registerCheckRoutes(api huma.API, h *handler, prefix string, mw huma.Middle
4545
Method: http.MethodPost, Path: prefix + "/patches/{patch_id}/checks",
4646
OperationID: fmt.Sprintf("create-check-v%s", prefix[5:]),
4747
DefaultStatus: 201,
48+
Security: authRequired,
4849
Middlewares: mw,
4950
}, h.CreateCheck)
5051
huma.Register(api, huma.Operation{
5152
Method: http.MethodPatch, Path: prefix + "/patches/{patch_id}/checks/{check_id}",
5253
OperationID: fmt.Sprintf("update-check-v%s", prefix[5:]),
54+
Security: authRequired,
5355
Middlewares: mw,
5456
}, h.UpdateCheck)
5557
}

‎pkg/api/comments.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ func registerCommentRoutes(api huma.API, h *handler, prefix string, mw huma.Midd
2929
huma.Register(api, huma.Operation{
3030
Method: http.MethodPatch, Path: prefix + "/patches/{patch_id}/comments/{comment_id}",
3131
OperationID: fmt.Sprintf("update-patch-comment-v%s", prefix[5:]),
32+
Security: authRequired,
3233
Middlewares: mw,
3334
}, h.UpdatePatchComment)
3435
huma.Register(api, huma.Operation{
@@ -44,6 +45,7 @@ func registerCommentRoutes(api huma.API, h *handler, prefix string, mw huma.Midd
4445
huma.Register(api, huma.Operation{
4546
Method: http.MethodPatch, Path: prefix + "/covers/{cover_id}/comments/{comment_id}",
4647
OperationID: fmt.Sprintf("update-cover-comment-v%s", prefix[5:]),
48+
Security: authRequired,
4749
Middlewares: mw,
4850
}, h.UpdateCoverComment)
4951
}

‎pkg/api/patches.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,13 @@ func registerPatchRoutes(api huma.API, h *handler, prefix string, mw huma.Middle
3333
huma.Register(api, huma.Operation{
3434
Method: http.MethodPatch, Path: prefix + "/patches/{id}",
3535
OperationID: fmt.Sprintf("update-patch-v%s", prefix[5:]),
36+
Security: authRequired,
3637
Middlewares: mw,
3738
}, h.UpdatePatch)
3839
huma.Register(api, huma.Operation{
3940
Method: http.MethodPut, Path: prefix + "/patches/{id}",
4041
OperationID: fmt.Sprintf("put-patch-v%s", prefix[5:]),
42+
Security: authRequired,
4143
Middlewares: mw,
4244
}, h.UpdatePatch)
4345
}

‎pkg/api/projects.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,13 @@ func registerProjectRoutes(api huma.API, h *handler, prefix string, mw huma.Midd
3030
huma.Register(api, huma.Operation{
3131
Method: http.MethodPatch, Path: prefix + "/projects/{id}",
3232
OperationID: fmt.Sprintf("update-project-v%s", prefix[5:]),
33+
Security: authRequired,
3334
Middlewares: mw,
3435
}, h.UpdateProject)
3536
huma.Register(api, huma.Operation{
3637
Method: http.MethodPut, Path: prefix + "/projects/{id}",
3738
OperationID: fmt.Sprintf("put-project-v%s", prefix[5:]),
39+
Security: authRequired,
3840
Middlewares: mw,
3941
}, h.UpdateProject)
4042
}

‎pkg/api/series.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ func registerSeriesRoutes(api huma.API, h *handler, prefix string, mw huma.Middl
3131
huma.Register(api, huma.Operation{
3232
Method: http.MethodPatch, Path: prefix + "/series/{id}",
3333
OperationID: fmt.Sprintf("update-series-v%s", prefix[5:]),
34+
Security: authRequired,
3435
Middlewares: mw,
3536
}, h.UpdateSeries)
3637
}

‎pkg/api/users.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,25 @@ func registerUserRoutes(api huma.API, h *handler, prefix string, mw huma.Middlew
2020
huma.Register(api, huma.Operation{
2121
Method: http.MethodGet, Path: prefix + "/users",
2222
OperationID: fmt.Sprintf("list-users-v%s", prefix[5:]),
23+
Security: authRequired,
2324
Middlewares: mw,
2425
}, h.ListUsers)
2526
huma.Register(api, huma.Operation{
2627
Method: http.MethodGet, Path: prefix + "/users/{id}",
2728
OperationID: fmt.Sprintf("get-user-v%s", prefix[5:]),
29+
Security: authRequired,
2830
Middlewares: mw,
2931
}, h.GetUserDetail)
3032
huma.Register(api, huma.Operation{
3133
Method: http.MethodPatch, Path: prefix + "/users/{id}",
3234
OperationID: fmt.Sprintf("update-user-v%s", prefix[5:]),
35+
Security: authRequired,
3336
Middlewares: mw,
3437
}, h.UpdateUser)
3538
huma.Register(api, huma.Operation{
3639
Method: http.MethodPut, Path: prefix + "/users/{id}",
3740
OperationID: fmt.Sprintf("put-user-v%s", prefix[5:]),
41+
Security: authRequired,
3842
Middlewares: mw,
3943
}, h.UpdateUser)
4044
}

0 commit comments

Comments
 (0)