feat: experimental defineRouteMeta

[eriksLapins]

🔗 Linked issue

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

I added the option to change the default provided schema directly in the server route file with defineRouteMeta, which can take in any key: value pair, with one defined in this PR - openAPI operations object, which will amend the default schema with types inferred from OperationsObject in openapi-typescript

This solves the issue that we can get better looking openapi documentation with better support

Possibly resolves the problem shown in discussion #2056

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[eriksLapins]

Also, I wanted to add a test for the defineOpenAPISchema function, but it errors out with
Failed to load url #internal/nitro/virtual/server-handlers if I load in the function as below

or Failed to load url #internal/nitro if I load the added function from #internal/nitro/routes/openapi

My idea was to add an additional preset with something like:

import { describe, expect, it } from "vitest";
import { defineOpenAPISchema } from "../../src/runtime/routes/openapi";
import { useStorage } from "#internal/nitro";


describe("nitro:openapi:schema-definition", () => {
    it("stores the result in useStorage", async () => {
        defineOpenAPISchema({
            routeBase: '/api/test',
            method: 'get',
            schema: {
                tags: ["test"]
            }
        })

        const storage = await useStorage("/api/test").getItem('openapi-get');

        expect(storage).toBe({
            routeBase: '/api/test',
            method: 'get',
            schema: {
                tags: ["test"]
            }
        })
    })
})

[nuxt-studio]

✅ Live Preview ready!

Name	Edit	Preview	Latest Commit
nitro	Edit on Studio ↗︎	View Live Preview	21264e2

[pi0]

This looks really promising and sorry being delayed. I might need time until 2.10 release to properly test it.

(in the meantime you don't need to rebase I can happily handle rebase once ready to check on it 👍🏼 )

[septatrix]

Definitely looks like a nice improvement. I am still mostly looking forward to automatically inferring the type (see #938) but this is a good compromise for the time being.

What I do not like is that is seems to only support object literals (based on reading the code, please correct me if I am wrong). No real evaluation for the route metadata is possible. This can and will confuse a lot of people. My first though was that this could be used with zod to generate zome of the types automatically but this does not seem feasible.

[pi0]

Thanks for your initiatives on this dear @eriksLapins. I have made some refactors in the way it works to experiment alternative approach for Nitro.

The meta is scanned using a rollup plugin now to allow HMR and uses a native parser of rollup + AST to Object transform and is only enabled with an experimental open API flag.

[atinux]

How can we share the validation (let's say I am using zod) between the route meta and the readValidatedBody for example?

[pi0]

It is experimental and not for validation right now.

[rmarquet21]

@pi0 Any idea when this will be in production and not just on the "nightly" version?

[pi0]

2.10 release no ETA. Also mind you, this API is likely to completely change into event handler object format nothing to rely on.