Статический файл swagger.json

[zerobig]

Готовить файл описания swagger.json не динамически из описания заданного кодом, а использовать статический файл подготовленный через какой-нибудь CLI. И описания тогда парсить из комментариев к функциям HTTP сервисов.
Кажется интересная тема для развития.
Плюсы:

• традиционное место для описания, которое находится рядом с описываемым кодом;

Минусы:

• требуются отдельные действия не только на то, чтобы поддерживать описание в актуальном состоянии, но ещё и на внедрение результата работы CLI в конфигурацию. Впрочем, это можно автоматизировать.

[zerobig]

626f84a - добавил пример как описание OpenAPI могло бы выглядеть в комментарии к функциям самого HTTP сервиса. Как реализовать описание объектов ( в данном случае TestObject и TestPostObject) пока не придумал.

[zerobig]

Была идея использовать рекомендации фирмы 1С по оформлению комментариев. Но я вижу по крайней мере два недостатка:

1. Функции HTTP сервисов никогда не вызываются из кода 1С (и не могут быть вызваны). Следовательно комментарии в стиле 1С там не нужны.
2. Комментарии в таком стиле не описывают все необходимые типы данных и структуры, которые используются в спецификации OpenAPI. Следовательно так или иначе придётся изобретать собственный велосипед.

На данный момент, для примера, я использовал вариант предложенный вот этой разработкой. Из плюсов такого подхода, назвал бы лаконичность.

Так же есть вариант использовать XML схему комментариев Microsoft. Этот вариант мне меньше нравится т.к. изначально придумывался для языка с чёткой типизацией. Следовательно многих моментов, которые выводятся из типов данных, в этой спецификации нет.

Резюме:

1. Единого признанного формата описания спецификации OpenAPI в комментариях к коду не нашел.
2. Свой велосипед строить не буду. Выберу существующий формат и буду писать библиотеку под него.

[kuzyara]

Не понял как описывать например схему для массива структур в параметрах

[zerobig]

Не понял как описывать например схему для массива структур в параметрах

Ну, наверное как-то так:

Swag_ФормированиеОписаний.ОписаниеСвойстваОбъекта("Имя", "ОписаниеСвойства", "array");