OpenAPI3 - как бороться с несколькими классами с одинаковым именем метода? - PullRequest
Новая
       105

OpenAPI3 - как бороться с несколькими классами с одинаковым именем метода?

0 голосов
/ 09 ноября 2019

Я бы хотел, чтобы OpenAPI (3) моделировал API, например: 

class Class1{
   Class1 get() {...}
}

class Class2{
   Class2 get() {...}
}

В действительности имена методов сопоставляются с operationId, а имена классов сопоставляются с tags. По крайней мере, для чванливого codegen это правда. (https://github.com/swagger-api/swagger-codegen).

Однако, когда у меня есть спецификация: 

paths:
  /class1/get:
    get:
      operationId: get    <<<<<
      tags: Class1 
      responses:
         ...
  /class2/get:
    get:
      operationId: get    <<<<<
      tags: Class2 
      responses:
          ...

... и https://editor.swagger.io/, и swagger-codegen жалуются, что идентификатор операции не уникален (чтоне).

Похоже, что рекомендуемый подход: 

class Class1{
   Class1 getClass1() {...}
}

class Class2{
   Class2 getClass2() {...}
}

... для объединения имен методов.

Но, чтобы быть ясным, яЯ не хочу, чтобы имена моих методов были уникальными среди всех классов. Обычно это кажется крайне плохим для развития API, так как каждый раз, когда мы добавляем метод, есть вероятность, что в какое-то время в будущем мы хотим добавить метод с аналогичным именем в другой класс. Если у нас не было предвидения включать имя класса в каждое имя метода , нарушение обратной совместимости для исправления схемы именования кажется неизбежным.

Кроме того, это приводит к очень многословным и уродливым API.

Итак, это лучший и единственный подход?

...