feat: experimental openapi define schema in server route files

[eriksLapins]

🔗 Linked issue

❓ Type of change

• [x] 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• [ ] 🐞 Bug fix (a non-breaking change that fixes an issue)
• [x] 👌 Enhancement (improving an existing functionality like performance)
• [x] ✨ 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

• [x] I have linked an issue or discussion.
• [x] 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[bot]]

✅ Live Preview ready!

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

[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 👍🏼 )

[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.