3 ms·
I've built ~12 web APIs in the last few years across various languages (TypeScript, C#, and Kotlin). You should always design first. I'm a longtime Open API Sp
by smt88 6y ago
I've built ~12 web APIs in the last few years across various languages (TypeScript, C#, and Kotlin).
You should always design first. I'm a longtime Open API Spec user, so I build the spec from scratch in Apicurio Studio or Stoplight. (I highly recommend keeping it in JSON, as the YAML specs are horrendous to read/edit.)
If you're very attached to your language of choice, there are usually tools you can use to annotate your data models and controller classes, and then you can generate your Open API Spec file from there.
The benefit of all this is that your public docs are programmatically bound to your type system (hopefully, assuming you're using a strongly typed language). If your spec changes, your code won't compile anymore.
You can also use your spec file to generate models/controllers (if you did spec-first instead of the annotation option), as well as unit tests. You can import it into Postman. It's very useful.
So our compile process is something like:
1. Lint the Open API Spec file with something like Spectral
2. Generate models and controllers from Open API Spec (which are imported as base classes and are not modified by humans)
3. Compile
Unfortunately, the existing generation of model generators for C# don't handle null well, so you lose out a huge benefit of the strong typing. TypeScript and Kotlin are fantastic about that, though. In general, I would recommend Kotlin today because it has the best combination of ecosystem and language, whereas C# has a great ecosystem but frustrating nominal typing system (until C# 9 anyway) and TypeScript is built on the shantytown that is JavaScript/npm.