mnahkies
commented
11 months ago I definitely agree that it generally makes sense for applications to expose the schema they were built with on an endpoint (and generally I expect them to additionally expose rendered docs using redoc / whatever)
With regards to #81 I was imagining something that would act as a convenience method for doing this, where you could optionally provide a route to expose the schema and rendered docs.
I'm not 100% sure what that interface should look like yet, or when I'll get to it though.
The way I currently tend to structure my projects looks something like:
├── Dockerfile
├── openapi.yaml
├── package.json
├── README.md
├── src
│ ├── config.ts
│ ├── database/
│ ├── generated.ts
│ ├── index.spec.ts
│ ├── index.ts
│ ├── middleware/
│ ├── models.ts
│ ├── routes/
│ └── schemas.ts
├── tsconfig.json
└── yarn.lockAnd I'd include the openapi.yaml in my docker image, making it readily available to serve as a static file at runtime.
With the revised approach of providing a router parameter to bootstrap, you could take a similar approach and mount an additional route on it easily enough, in the simplest instance something like:
const router = createRouter(...)
router.get('/openapi.yaml', ctx => {
ctx.body = fs.readFileSync('./openapi.yaml', 'utf-8')
ctx.status = 200
})
bootstrap({router, ...})(adjust route / filepath / read file content once at startup / etc as appropriate)
The other approach I've taken in the past has been to have a centralized/mono repository of openapi definitions such that the content of the definition gets pulled at the time of generation. In this instance I'd probably be inclined to just curl it to a file still and commit it.
In the golang example you linked, I imagine the motivation for embedding as a base64 string is related to wanting to have a single static binary to ship (though I think using the recent stdlib addition https://pkg.go.dev/embed would make more sense now - you can still do stuff like only gzip it once if you really want, though I'd be surprised if the endpoint was getting called often enough to need to bother).
Are you doing some kind of bundling or making use of https://nodejs.org/api/single-executable-applications.html that makes embedding the definition into the source code particularly desirable?
Generally I think it works out better in terms of VCS history to keep it as a separate flat file if possible.
ADRFranklin
This should definitely be it's own issue (coming from this issue) and this shouldn't be strictly related to #81.
So I have used other projects (mainly golang related) for openapi, and I was spoiled with the option of having the spec embedded into the server via base64 encoding. I'll provide this link here, that gives a good example of how that may look.
Unlike issue #81 this is not about providing documentation, but rather exposing the openapi schema itself, which can be served by the application itself, allowing someone to generate a client from that schema for the exact version of software that is hosting it. I've personally always found this way of doing it to be fitting for almost all apps that I have written using openapi.
Now I am not sure how involved you want this process to be, I personally would be fine with having it generated and a few helper functions to decode it, cache it, and then provide a function to get the cached contents of which could be served on any endpoint I wish without any forced requirements. However maybe you want the process to be more controlled, and maybe you have some function that takes an endpoint string, and then the library handles serving it up on that endpoint, with very little effort on the developer using it.
I hope this is something that makes it into the library in some way, as I see it being very beneficial.