search

zerotier / zerotier-one-api-spec

ZeroTier
https://zerotier.com
3 stars 0 forks source link

Do a pass of fixing up the naming #3

Open laduke opened 9 months ago

laduke commented 9 months ago

Some of the names are long. They are probably inconsistent with each other. This appears as long awkward names in generated clients. Let it marinate for a bit then update it. Let me know what you don't like.

laduke commented 8 months ago

One nice thing, in openapi-ts, it doesn't use the long names, it uses the paths /api/controller, which don't change almost ever. If you're using the json-schema for AJV or something, the name are annoying and could change.

JohnGuan commented 2 weeks ago

I once wrote a full version of openapi when this repo didn't exist, with a lot of operationId and type/object tweaks. For your reference.
Link: https://github.com/JohnGuan/zerotierone-openapi/blob/main/zerotierone-openapi.yaml

laduke commented 2 weeks ago

thanks for writing. the spec is in use in a few places with generated apis so it might be a pain to change things. will have weigh the pros and cons

JohnGuan commented 2 weeks ago

At least in the operationId part, in the performance of ts, all APIs use operationId to generate function names, which is very unreadable. Is this part modifiable?

JohnGuan commented 2 weeks ago

Sorry, I just realized that this seems to be a generated OpenAPI file written with TypeSpec. I think I’ll take some time to learn more about TypeSpec—it looks like a good way to define APIs and doesn’t seem as painful as writing OpenAPI in YAML directly.

I did a quick search and found some information about operationId, which appears to be the reason behind the unusual naming issue. https://typespec.io/docs/libraries/openapi/reference/js-api/functions/resolveoperationid/

laduke commented 2 weeks ago

I think we can give better operation IDs a try. The generators we've used so far and depend on just use the path names.

I looks like the readme needs a little update. The tests require docker now. They don't touch your local zerotier-one instance.