Статический файл swagger.json about swagger-1c HOT 4 OPEN

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

from swagger-1c.

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

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

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

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

Резюме:

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

from swagger-1c.

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

from swagger-1c.

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

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

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

from swagger-1c.