найди в моей документации, чтобы параметр был, а соответствующего кода не было

да я смотрю на гите, таких параметров тоже не вижу

откуда взялась эта документация к ефильтру тогда

найди в моей документации, чтобы параметр был, а соответствующего кода не было

http://docs.evo.im/04_extras/dlmenu.html hereId

где там такой параметр

где там такой параметр

https://github.com/evolution-cms/evolution/blob/1.4.x/assets/snippets/DocLister/core/controller/site_content_menu.php#L503

так я же не про это говорю

вот если бы он в документации был, а в коде не было

вот если бы он в документации был, а в коде не было

да ладно не отмазывайся))) было было

не было

потому что я документацию пишу по коду, а не наоборот

потому что я документацию пишу по коду, а не наоборот

А правильно в начале документацию, а потом код😁

это только в modx такое возможно

это только в modx такое возможно

На самом деле нет. И это нормальная практика

ну так это не документация, а тз типа

А правильно в начале документацию, а потом код😁

Про разработку через тестирование я слышал, но про разработку через документирование... Это какое-то новый тренд?

Теоретический пример. Ты пишешь api, для работы мобильного приложения. Там условно есть функции фильтра, каталога, оформление заказа и чата. Так вот на много проще заранее расписать все параметры, а потом по этой доке всё писать. И у тебя получается вначале дока, а потом под неё решение

Можно и наоборот, но в данной ситуации этот вариант проще для всех

Можно и наоборот, но в данной ситуации этот вариант проще для всех

самый простой - не писать доки))

Теоретический пример. Ты пишешь api, для работы мобильного приложения. Там условно есть функции фильтра, каталога, оформление заказа и чата. Так вот на много проще заранее расписать все параметры, а потом по этой доке всё писать. И у тебя получается вначале дока, а потом под неё решение

На берегу продумать все возможные параметры нереально. А если следовать твоему примеру, то получится, что либо документация устареет пока ты код пишешь. Либо код будет сильно упрощен, т.к. ты старался четко следовать заранее написанной доке

да, лучше не писать доки, чем писать абы что

@Pathologic93 прав, это больше ТЗ, но никак не готовая дока

На берегу продумать все возможные параметры нереально. А если следовать твоему примеру, то получится, что либо документация устареет пока ты код пишешь. Либо код будет сильно упрощен, т.к. ты старался четко следовать заранее написанной доке

Ну понятное дело что расширяться будет

В целом это даже не дока, а описание работы api

Ну понятное дело что расширяться будет

Если доку так и так писать хочешь, то лучше это делать после того, как код готов.

В целом это даже не дока, а описание работы api

Для описания работы API как правило проще просто заранее моковые данные подготовить.

Просто я когда два года занимался этими апишками, как раз начинал с расписывания всех интерфейсов и параметров, а потом писал апи. Но понятное дело, что по ходу написания данные менялись.

А вообще для API очень крутая штука есть - https://raml.org/

Через нее документирование божественно

Изначально тоже делал код, а потом доку. Но в итоге пришёл к выводу что выше описанное решение проще

Ну давай будем честны, документирование API и параметров к сниппетам это разные вещи

Хотя да, это скорее ТЗ, чем дока. Но по сути это всё потом передавалось мобильщикам и они были очень рады так подробно расписанным вещам

Ну давай будем честны, документирование API и параметров к сниппетам это разные вещи

+ согласен, я просто хотел привести пример что бывает и процесс дока->код

Попробуй RAML для документирования API

+ согласен, я просто хотел привести пример что бывает и процесс дока->код

но "дока -> сниппет" – нет))

но "дока -> сниппет" – нет))

А вдруг это сниппет с апишкой?

Кто не успел, тот опоздал)

Кто не успел, тот опоздал)

не опоздал)

Попробуй RAML для документирования API

а в таком духе не удобнее? https://online.moysklad.ru/api/posap/1.0/doc/index.html#pos_begin-%D0%BF%D1%80%D0%B8%D0%B2%D1%8F%D0%B7%D0%BA%D0%B0-%D1%82%D0%BE%D1%87%D0%BA%D0%B8,-%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%D0%B0-%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-token-post

а в таком духе не удобнее? https://online.moysklad.ru/api/posap/1.0/doc/index.html#pos_begin-%D0%BF%D1%80%D0%B8%D0%B2%D1%8F%D0%B7%D0%BA%D0%B0-%D1%82%D0%BE%D1%87%D0%BA%D0%B8,-%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%D0%B0-%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-token-post

Ну так ты шаблон для негерации можешь любой исплоьзовать

Ну это была дока основанная на рестарт, я примерно так и делал, только не до конца соблюдал эти принципы.

Сама дока формируется из таких файлов

Я их не знал просто

Ну так ты шаблон для негерации можешь любой исплоьзовать

аааа.. я думал это особенности

Сохранил 😁

Т.е. каждый запрос описывается в отдельном файле. Моковые запросы в отдельном файле описываются, моковые данные - в другом файле так же с документацией каждого поля и типа.

А уже на основе этих доков генерируется html. Я просто дефольтный шаблон использовал, т.к. дизайн не важен.

RAML удобен тем, что легко потом ориентироваться по доке и если что-то в одном месте поменял,то при компилации тебе скажут: ошибка. тут такой тип, а там другой. Или наоборот, во всех других месах изменится данные

Например, даты я описываю как DateTime_1C (по просьбе 1Сника везде использовать его формат дат). А уже в файле DateTime_1C описываю что это за объект. И если потом вдруг изменится описание или формат вывода, то правиться это всего в 1 месте. Так можно описывать и более сложные объекты которые зависят от других объектов. Для пример объект, Order зависит от объекта OrderPay который зависит еще и от DateTime_1C

В общем рекомендую познакомиться с RAML всем, кто часто пишет API

спасибо!

спасибо!

Незачто)

а в таком духе не удобнее? https://online.moysklad.ru/api/posap/1.0/doc/index.html#pos_begin-%D0%BF%D1%80%D0%B8%D0%B2%D1%8F%D0%B7%D0%BA%D0%B0-%D1%82%D0%BE%D1%87%D0%BA%D0%B8,-%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%D0%B0-%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-token-post

Через https://apiblueprint.org/ построена дока. Судя по описанию такая же хрень, что и RAML.

Через https://apiblueprint.org/ построена дока. Судя по описанию такая же хрень, что и RAML.

вот как раз такая чаще встречается

raml vs blueprint

Холиварная тема судя по гуглу

Холиварная тема судя по гуглу

значит и то и другое востребовано, а дальше уже кому что больше по душе

Под Laravel автогенератор нашел на основе raml https://github.com/RJAPI/raml-json-api

Пишешь доку, код сам генерируется)

Пишешь доку, код сам генерируется)

мда.. такого поворота никто не ожидал))

А как же Swager для апишек?

Или это из другой оперы?

С телефона особо не могу понять прелесть рамл

А как же Swager для апишек?

это еще один способ документирования. Такой же как и Raml или BluePrint. Разница в синтаксисе, уровне вхождения и т.п.

Raml по моим ощущениям проще понять человеку даже далекому от программирования

Надо будет посмотреть. Свагер по опыту сродни стандарту последнее время, но там не всё мнеу нравится

Надо будет посмотреть. Свагер по опыту сродни стандарту последнее время, но там не всё мнеу нравится

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

👍

В крупных компаниях возможно и Swagger юзают. Хотя RAML если верить описанию проекта, тоже не пальцем деланый.

AngularJS, Google, VMWare, Cisco, MuleSoft проект этот развивают

откуда взялась эта документация к ефильтру тогда

Спроси у того, кто эту чушь писал. Причем тут фильтр, он божественен и работает на 100 млн тв:)

а кто писал?

Не знаю, наверно dzuryn или кто там его форкал. По своему форку и писал похоже, чтобы всех запутать

а блин

вообще там написано, что ты писал ((:

Я же тут уже подымал бучу по переименованию ветки d

Да там просто копипаст с моего ридми плюс те параметры из веток -d, которых никто не видел