How do I notate a path with security but no operations?

Question

My api is split between some public and some secure routes. All the secure routes are children of /secured/ so I want to mark that once instead of marking every operation path secure.

so I have routes like

/ // nothing here
/healthcheck //open route, can be used to make sure API is up
/login              //generates the cookie and tokens
/secured/users      //requires login and lists users
/secured/resources  //requires login and lists resources
/secured/others     //etc.

My API has the middleware for login checks on the secured path so everything below that has to have cookies and tokens checked. So I want my docs to match. I know I can mark security at the root, or at every endpoint, but how can I mark it just once for the secured path?

I'm trying something like:

paths:
  /healthcheck:
    get:
      [the get activity]
  /login:
    post:
      [yada yada yada]
 /secured:
    security:
      [security rules]
 /secured/users:
    get:
    post:
    put:
    delete:

but that seems to throw errors. Any thoughts on how I can acomplish this outside of just putting the security on every route and operation?

Answer 1

I know I can mark security at the root, or at every endpoint, but how can I mark it just once for the secured path?

This is not possible, mainly because OpenAPI does not have a concept of subpaths. In OpenAPI terms your API does not actually have the /secured path - it has /secured/users, /secured/resources etc.

If your API has more secured operations that non-secured ones, you can define the security globally and disable security for operations that don't use it:

security:
  - mySecurity: []

paths:
  /healthcheck:
    get:
      security: []  # <---
      ...
  /login:
    post:
      security: []  # <---
      ...