✅ Request method missing: HEAD

[pepegc]

Any reason HEAD (the request method) is not supported?

[RobinTail]

It's special in a way that it should replicate GET except the response body.
Responding is delegated to user domain (customizable ResultHandler), but implementing this requirement would have to be sort of opinionated.
Not sure yet how to address it properly, @pepegc
Started #2816

[RobinTail]

I found an interesting note in Express documentation, @pepegc :

The app.get() function is automatically called for the HTTP HEAD method in addition to the GET method if app.head() was not called for the path before app.get().

https://expressjs.com/en/api.html#app.METHOD

So that maybe there is no need for all that

UPD: Tested it. It really works!
Though, CORS headers do not include HEAD.

[RobinTail]

No extra handling required for res.send() — it automatically sends Content-Length instead of a body for requests having HEAD method:
https://expressjs.com/en/api.html#res.send

[RobinTail]

🚀 v24.7.0, @pepegc
Thank you for the contribution!

[pepegc]

thank you!

[GreaterTamarack]

@RobinTail I am curious, is there a way for us to disable the addition of HEAD routes to openapi documentation?

e.g. we are trying to create a minimal openapi.doc, and currently have a structure like below. It would be convenient to not have HEAD requests auto-added to the doc.

/*** Define Routes ***/
const swaggerUIRoutes: Routing = {
  "get /foo": getFoo,
  "post /foo": createFoo,
  "put /foo/:uuid": updateFoo,
};

const allRoutes: Routing = {
  ...swaggerUIRoutes,
  "get /health": healthHandler,
  "post /admin/fizz": parallelTestFirstCyberQuoteCSVHandler,
}

//pass swaggerUIRoutes into open api spec...

[RobinTail]

well... I though about making it configurable, but later came to conclusion that since HEAD is an automatic built-in feature of Express itself, it would be better to reflect the reality.
However, if you could explain what exactly is inconvenient in having HEAD in documentation, I could possibly reconsider, @GreaterTamarack
Please let me know.

[GreaterTamarack]

Thank you for clarifying that we can't toggle it right now. I am not sure the experience you are looking to deliver with the library here, so I definitely defer to your judgement, but will share my experience.

My key focus is designing a simplified api user experience. I would prefer that a consumer of my service doesn't need concerned about endpoints they don't need.

Additionally, as an express-zod-api user, I was surprised to see these HEAD methods show in our documentation when I didn't program anything specific for them. I read the changelog and the discussion, and I can appreciate that HEAD is automatically handled by express, and thus adding it in is reflective of reality. That said, when I think about the DX for an api consumer of my service, I am already 'hiding reality' like a health endpoint, internal routes, etc.

In the same way, I am seeking the ability to 'hide' HEAD requests. There is an argument that this is similar to OPTIONS - express would automatically handle an OPTIONS request to list what methods are available for an endpoint, and can technically be overridden with a custom implementation, but usually it is not shown on docs.

Thanks for your time and consideration!

I have a sample app snippet I can share below, but here is the end result I am trying to avoid. Especially as the api grows, there may be many GET methods.

Here is the index.ts that generated this:

import {
  createConfig,
  createServer,
  defaultEndpointsFactory,
  Documentation,
  Routing,
} from "express-zod-api";
import z from "zod";
import fs from "fs";
import express from "express";
import swaggerUi from "swagger-ui-express";

/*** Dummy Endpoints... ***/
const getHandler = defaultEndpointsFactory.build({
  method: "get",
  input: z.object({}),
  output: z.object({}),
  handler: async () => {
    return await Promise.resolve({});
  },
});

const postHandler = defaultEndpointsFactory.build({
  method: "post",
  input: z.object({}),
  output: z.object({}),
  handler: async () => {
    return await Promise.resolve({});
  },
});

/*** Define Routes ***/
//These should show on swaggerui...
const swaggerUIRoutes: Routing = {
  "get /foo": getHandler,
  "post /foo": postHandler,
};

//These should NOT show on swaggerui...
const allRoutes: Routing = {
  ...swaggerUIRoutes,
  "get /health": getHandler,
  "post /admin/fizz": postHandler,
};

/*** Configure Server & Serve Swagger UI ***/
//Base config
const baseConfig = createConfig({
  http: { listen: 3000 },
  cors: true,
});

//Generate the doc using the swaggerUIRoutes
const publicSwaggerDoc = new Documentation({
  routing: swaggerUIRoutes,
  config: baseConfig,
  version: "1.0.0",
  title: "My Public API",
  serverUrl: "http://localhost:3000",
});
try {
  fs.mkdirSync("./docs", { recursive: true });
  fs.writeFileSync("./docs/public-swagger.json", publicSwaggerDoc.toString());
} catch (e) {
  throw new Error("Could not write documentation file.", { cause: e });
}

//Finalize config with a before routing section to serve swaggerui
const config = createConfig({
  ...baseConfig,
  beforeRouting: ({ app }) => {
    const serverUrl = "http://localhost:3000";
    console.log(`serving docs at ${serverUrl}/docs`);
    const doc = {
      ...publicSwaggerDoc.getSpec(),
      servers: [{ url: `${serverUrl}` }],
    };
    app.use(
      "/docs",
      swaggerUi.serve,
      (req: express.Request, res: express.Response, next: express.NextFunction) => {
        swaggerUi.setup(doc)(req, res, next);
      }
    );
  },
});

/*** Start Server ***/
await createServer(config, allRoutes);

[RobinTail]

I understand, @GreaterTamarack .
Thank you for the clarification.
I will make it configurable: but it would be opt-out feature (enabled by default).

[RobinTail]

#2872

[RobinTail]

🚀 v25.1.0, @GreaterTamarack