Add operation ids to external API description

[christianlupus]

Closes #1421

[github-actions]

Test Results

     21 files     952 suites   5m 19s ⏱️
   496 tests    496 ✔️ 0 💤 0 ❌
3 472 runs  3 471 ✔️ 1 💤 0 ❌

Results for commit 789ca85.

♻️ This comment has been updated with latest results.

[christianlupus]

@Leptopoda, please have a look at this PR if that is as you think it useful.

[codecov]

Codecov Report

Merging #1445 (789ca85) into master (c855a5d) will not change coverage.
The diff coverage is n/a.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1445   +/-   ##
=======================================
  Coverage   79.35%   79.35%           
=======================================
  Files          86       86           
  Lines        2548     2548           
=======================================
  Hits         2022     2022           
  Misses        526      526           

Flag	Coverage Δ
integration	21.23% <ø> (ø)
migration	5.92% <ø> (ø)
unittests	56.16% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[Leptopoda]

I don't think underscrore is the right way to go.
I can only speak for dart/flutter but I think the general codestyle is the same on java/kotlin aswell.

Depending on the generator used it will generate something like:

final API _api = API();
final CategoriesApi _categoryAPI = _api.categories;

final Response<RecipeStub> _response= await _categoryAPI.recipes_in_category(id: "12345678");

if(response.code == 200){
  print(response.data)
}

In this case having category in the description is a bit verbose as we call a method to get the recipes on the categoryAPI object anyways. Also this does not easily resolve the http method used.

Taking those and the aforementioned camelcase into consideration I'd name this particular endpoint getRecipesor getRecipeStub resulting in something like:

final _api = API();
final _categoryAPI = _api.categories;

final _response = await _categoryAPI.getRecipes(id: "12345678");

if(response.code == 200){
  print(response.data)
}

As dart can do type inference I could even leave out the type declarations as seen above.

---

Obviously I'm biased and prefer the style of the language I like/use most but I think the same should at least apply to java/kotlin. (iirc the preferd method naming scheme is camelcase and at least the official swagger kotlin generator does produce objects for each api endpoint).

---

Finally I've also found a few other problems with the spec that I'd like to discuss as they might also need server side changes while hopefully not being considered breaking. Therefore I'd not close the issue #1421 and change the PR content.

I've experimented with some changes already and played arround with them locally so theres nothing final or PR ready as of now (the reason I didn't go forward with them yet) but I'll attach my current version below.
I mainly changed some response objects to be named (the main reason this discuaaion started) and yes I've made the id an integer instead of a String but my generator does not like it the other way and as said this is still a WIP for me :)

objects.txt
openapi-cookbook.txt

[christianlupus]

I don't think underscrore is the right way to go. I can only speak for dart/flutter but I think the general codestyle is the same on java/kotlin aswell.

Yes, it is true that PascalCase and camelCase are the typical stylings for many modern languages. However, there are case-insensitive languages and these fail at either of these. Using kebab-case works well in YAML but might cause trouble with code generation (the minus might be a subtraction sign).
This is the reason, I went for snake_case.

In general, this can be discussed if we keep the names unique with case-insensitive comparisons.

[...]
In this case having category in the description is a bit verbose as we call a method to get the recipes on the categoryAPI object anyways. Also this does not easily resolve the http method used.

Here there is no real alternative. According to the official documentation the operation ID must ba a unique string.

As we have a way to get all recipes for a keyword, for a category, in a search and all recipes unconditionally, we must use appropriate names for these.
This means that the duplication of context is mandatory in some sense by the OpenAPI standard.

Finally I've also found a few other problems with the spec that I'd like to discuss as they might also need server side changes while hopefully not being considered breaking. Therefore I'd not close the issue #1421 and change the PR content.

I've experimented with some changes already and played arround with them locally so theres nothing final or PR ready as of now (the reason I didn't go forward with them yet) but I'll attach my current version below. I mainly changed some response objects to be named (the main reason this discuaaion started) and yes I've made the id an integer instead of a String but my generator does not like it the other way and as said this is still a WIP for me :)

Let's focus here on the operation ID in this PR.

[Leptopoda]

Here there is no real alternative. According to the official documentation the operation ID must ba a unique string.

Yeah I forgot about that :(
also discussed here: OAI/OpenAPI-Specification#381
We'll need to also include that information.

Yes, it is true that PascalCase and camelCase are the typical stylings for many modern languages.

Can you please name me any relevant one? Also I can't imagine someone writing an API client in languages like Pascal :)
And if my 5 second search isn't wrong all [for us] relevant languages (Obj-C/Swift, php, JS/TS, Java/kotlin, dart) are both case sensitive and do also prefer camelCase for their functions.

Also a look at the languages supported by the official swagger/openapi codegenerator reveals that case insensitivity probably isn't a Problem.

ActionScript, Ada, Apex, Bash, C, C#, C++, Clojure, Crystal, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell, Java, Jetbrains HTTP Client, Julia, k6, Kotlin, Lua, Nim, Node.js/JavaScript, Objective-C, OCaml, Perl, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift, Typescript

I could only imagine things like Haskell being problematic as they require method names starting with a capital letter (AFAIK).
Finally again: who is expected to write a client in Haskell? Also the generator should usually be smart enough to handle this stuff.

[christianlupus]

/approve

[nextcloud-cookbook-bot]

Automatically approved by GitHub action on behalf of /approve