evert
commented
4 years ago Thanks for the nice feedback!
A few things that might be notable:
This:
async get(ctx: Context<GetThumbnailRequest>) {Already works. Context is a Generic, and the first type is type of the request, the second (if specified) is the response.
The syntax for this:
/** Redirects to a presigned S3 url to the a png thumbnail of the original artwork file. */
return new Redirect({
code: 302,
target: url
});Is currently:
ctx.redirect(302, url);I don't think this project will ever evolve to a point where it can automatically generate OpenAPI definitions, there's a couple of reasons:
- I believe that your OpenAPI definition, if anything, should generate the API. I don't think the API should generate the OpenAPI definitions. I believe API design should inform the implementation. So the kind of OpenAPI facilities we'll have in the future will likely be the exact reverse of that. I very bunch believe in a docs-first approach.
- For the people that like this sort of thing, I hope that one day a project will spawn like Nest.JS, that uses Curveball, much like Nest currently uses express under the hood.
One thing that we'll probably implement soonish (as a first step towards OpenAPI support) is deep JSON-schema integration.
Ideally I want the syntax for this to look something like:
class ThumbnailController extends Controller {
@validate('http://my-api/schemas/my-thumbnail.json');
async get(ctx: Context<GetThumbnailRequest>) {
/// ...
}
}We're using this syntax for the projects we're working on, which is very similar:
class ThumbnailController extends Controller {
async get(ctx: Context<GetThumbnailRequest>) {
const body = validate<GetThumbnailRequest>(
'ctx.request.body,
'http://my-api/schemas/my-thumbnail.json'
);
}
}Validate in this case was returning the body, but this was before Typescript assertion functions.
I'd imagine something very similar could work for OpenAPI, especially since it's now compatible with json-schema. I think similar OpenAPI will probably have to be a community contribution as we're not using this yet, and I'm not comfortable adding features that are not in use and go through some level of real-world scenarios and maintenance cycles. The devil is in the edge-cases =)
Cmacu
Lindsor
rettgerst
ericmorand
hello, I saw the introductory article in my google discover feed and was initially very impressed with curveball. and since you mention in your readme that you're looking for feedback I thought I'd write about one of the features I'd like to see.
NestJS is the server framework I currently use in my projects, coming from express. one of the major pulls to NestJS for me is its swagger plugin which allows me to automatically generate an OpenAPI specification file from the server source code. in turn, I use the OpenAPI Tools Generator to turn this spec file into API documentation and a strongly typed client for our frontend.
the major downside to Nest's approach is that it is heavily verbose and requires liberal use of decorators in order to provide all of the documentation metadata. here is an example of an actual api method from one of my projects where I use NestJS:
(this doesn't even get into the chore of writing DTOs)
and here is a mockup of what this same method might look like in a hypothetical future version of curveball:
not only is this mockup fewer lines of code, but I also find it more readable - it reuses existing language constructs instead of duplicating them, and the textual descriptions are written as comments rather than strings.
this api also retains all of the same data as the first example - the operationId is implied (thumbnail resource + get operation = 'getThumbnail'), the paremeter descriptions already exist in the method signature plus the jsdoc comments, and the response code as well as the response body schema can be inferred from the method's inferred response type.
tools like typedoc can produce surprisingly rich, human-readable documentation just from statically analyzing code, with very little additions to the original source - all the metadata you need is already there in the type system. I've received comments from my coworkers on how good my documentation is - I don't write documentation, I just write code, then run it through typedoc. it would be great to have a simlar experience with my http apis.