Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enable generated etapi client #3909

Merged
merged 5 commits into from
May 7, 2023
Merged

Conversation

mm21
Copy link
Contributor

@mm21 mm21 commented May 5, 2023

This enables etapi clients to be generated using openapi-generator. I've generated the python-nextgen client and verified all CRUD operations for notes, attributes, and branches.

The most sensitive change is adding attributeId/branchId path parameters to postAttribute/postBranch. I realize this may unfortunately break existing clients, but this is a requirement for OpenAPI - all methods need to take the same path parameters. See https://swagger.io/docs/specification/describing-parameters/#path-parameters:

Also remember to add required: true, because path parameters are always required.

The etapi.openapi.yaml changes are to fix validation errors:

  • Required fields of Attribute and Branch removed: these schemas are also used for patch wherein those fields can't be updated; generated model then fails validation when it's instantiated
  • Pass charset in response content-type: the content-type in Trilium's response is used as a dictionary key, so it needs to match exactly what's provided in the yaml
  • Python's built-in regex module doesn't recognize unicode property escapes (\p{L}, \p{N}), so replaced them with [^\s]+ (although this wouldn't be a big deal for me to just change locally)
  • Allow underscore in EntityId for branches
  • Allow negative timezone offsets
  • Add valid note types
  • Remove nonexistent required fields from AppInfo

I can work around these issues by modifying etapi.openapi.yaml locally and hacking up the generated code to omit the path parameters in postAttribute/postBranch, so this isn't necessarily urgent, but it would be really useful to be able to generate clients in various languages.

For reference, here's the command I used to generate a Python client:

openapi-generator-cli generate -i etapi.openapi.yaml -g python-nextgen -o ./etapi-client --additional-properties packageName=etapi_client --additional-properties projectName=etapi-client

@@ -20,7 +20,7 @@ function register(router) {
'isInheritable': [v.notNull, v.isBoolean]
};

eu.route(router, 'post' ,'/etapi/attributes', (req, res, next) => {
eu.route(router, 'post' ,'/etapi/attributes/:attributeId', (req, res, next) => {
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is rather PUT semantics, rather than POST.

Honestly it seems that the ETAPI OpenAPI spec is wrong, because it suggests the POST method requires the ID path param which isn't true. So I think we just need to fix the YAML file to better reflect the existing API.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and I tried to do that before by putting "parameters:" under each HTTP method, but it didn't work that way. For some reason I didn't think about moving POST into its own "/attributes" path rather than having it under "/attributes/{attributeId}", same for branches. But that worked like a charm and reduced this PR to only changes in the YAML file which is nice.

@zadam zadam merged commit 5676ff9 into zadam:master May 7, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants