СХ
Это reference, описание методов. А рядом ещё есть guides, где как раз описание всего с точки зрения того, как этим пользоваться. Вы считаете, что "описание API" — это только reference? Что тогда guides?
Size: a a a
2020 May 28
KS
Я говорю, что сие есть разные документы. Как у них и разделено, да.
KS
Описание АПИ — референс.
KS
„Инструкция“ какая-нибудь, если мы ищем русские термины, — это guides.
B
Ну и краткое описание того, что операция, собственно, делает.
представьте. Вы учитель. Первый день на работе. У вас есть две Маши Ивановых. и Вам надо поставить одной из них оценку. Как вам будет проще, что если вам сначала объяснят, какая Маша Иванова из двух получила эту оценку, или вы наугад поставите, а потом будете от руки переписывать весь журнал?
B
подход интересный, но не практичный
KS
Вы совершенно правы. :) Но если я их учу уже год, мне надо просто подглядеть, в какой строке журнала у меня рыжая Маша. А если мне для этого надо будет прочесть две страницы текста, где меня сперва будут учить их различать — мне будет не очень.
KS
Поэтому это и разные документы, отвечающие на разные вопросы.
KS
Ну ок, может быть разные разделы одного большего докеумента.
KS
Описанием АПИ из них является второй — для тех, кто понимает, что ему надо.
СХ
Я говорю, что сие есть разные документы. Как у них и разделено, да.
Вопрос, скорее, в терминологии. Я абсолютно согласна, что это должны быть разные документы, но в моей голове термин "описание API" — это совокупность reference, guides и, возможно, каких-то ещё материалов, которые все вместе описывают, как работать с API.
B
Вопрос, скорее, в терминологии. Я абсолютно согласна, что это должны быть разные документы, но в моей голове термин "описание API" — это совокупность reference, guides и, возможно, каких-то ещё материалов, которые все вместе описывают, как работать с API.
+++
KS
Тут, конечно, соглашусь.
СХ
Burrito
ну и в этом "описании" есть методы, с разными заголовками, разными параметрами, но одинаковым дескрипшн. На вопрос "в чем отличие?" автор этой апишки отвечает, что: апи не отвечает на вопрос когда какой метод вызывается. апи отвечает на вопрос как вызвать тот или иной метод, с какими параметрами и что будет при этом выполнено. принтер не знает ничего о работе кассы и не должен. называется инкапсуляция. запихивать инфу о кассе в инфу о принтере неверно
В любом случае я считаю, что описание методов должно ясно объяснять, что это за метод, для чего он нужен и чем отличается от других методов. Поэтому согласна, что если у разных методов одно и то же описание, то это не ок.
KS
Но тем не менее. В описании операций API принтера действительно нет места словам про кассу.
B
Тем не менее, это описание взаимодействия. А что и как взаимодействует, я не вижу.
СФ
Burrito
Коллеги, как вы думаете, что должно включать в себя описание метода в api? Должны ли описываться условия, при которых выполняется та или иная команда?
Мы на прошлой работе описывали вот что:
- бизнес-смысл самого действия метода
- параметры, их бизнес-смысл и ограничения на значения
- возвращаемое значение
- предусловия и постусловия: каким должен быть мир, чтобы можно было воспользоваться этим методом? как мир поменяется после выполнения метода?
- побочные эффекты и инварианты: что неочевидное поменяется после выполнения метода? что, наоборот, не поменяется?
- бизнес-смысл самого действия метода
- параметры, их бизнес-смысл и ограничения на значения
- возвращаемое значение
- предусловия и постусловия: каким должен быть мир, чтобы можно было воспользоваться этим методом? как мир поменяется после выполнения метода?
- побочные эффекты и инварианты: что неочевидное поменяется после выполнения метода? что, наоборот, не поменяется?
ДБ
Коллеги, вопрос по теме API. Есть swagger, разработчики описали примеры и методы. Рук-во хочет бумажный вариант для переиспользования на проектах. С чего мне начать? Я так понял, что дока к API условно делится на:
- Описание методов
- Кейсы использования методов
- Описание методов
- Кейсы использования методов
DS
Burrito
Тем не менее, это описание взаимодействия. А что и как взаимодействует, я не вижу.
Если ваш в принтер в какой-то момент решит работать с другой кассой (или вообще не с кассой), то дока моментально протухнет. А апи не поменяется никак.
B
Если ваш в принтер в какой-то момент решит работать с другой кассой (или вообще не с кассой), то дока моментально протухнет. А апи не поменяется никак.
эта не решит)