Какие есть способы ведения документации JSON/XML структур?

Question

[mindgrow]

Подскажите пожалуйста удобный способ, который позволяет вести документацию по xml/json контракту, а именно
- просматривать/редактивровать иерархическую структуру в виде дерева
- указывать тип значения каждого узла
- заносить документацию по каждому узлу; описание узла может занимать несколько абзацев

Какие практики используете? Что можете посоветовать?

Comments

[Kovalsky]

Swagger

[mindgrow]

Посмотрел, не подходит. В части документирования xml/json он не предоставляет возможности документировать узел и сворачивать/разворачивать узлы

Answer 1

[Сергей delphinpro]

Если ориентироваться на тег ajax, то можно предположить, что речь идет об ответах API. Тот же OpenAPI позволяет описать в том числе и структуру json ответов.

Comments

[mindgrow]

в нём можно описывать параметры запроса, но не структуру json\xml.
По структуре можно приложить только пример, без описания узлов.

Меня интересует чтобы по каждому узлу можно было добавлять комментарий значительных размеров и иметь возможность сворачивать/разворачивать узлы

Answer 2

[Saboteur]

https://en.wikipedia.org/wiki/SOAP не оно?

Comments

[mindgrow]

что оно?)) вы мне скинули ссылку на описание технологии SOAP, а я спрашиваю про методику документирования JSON/XML структур

[Saboteur]

В XML проблем с документацией структуры особо нет, а SOAP подразумевает, что это делается один раз на сервер, и все клиенты эту документацию свободно получают в любой момент
ПРо JSON там нет.

[mindgrow]

Saboteur, я рад за вас что у вас нет проблем с документированием xml. У нас большой документ играет роль в бизнес-логике, поэтому должен иметь описание.

Всё же по поводу SOAP не понятно, что вы хотите предложить? Использовать технологию? Но вопрос-то про документирование структурированных документов. В случае soap - это тоже xml. В части документирования в вашем ответе ничего нет.

Answer 3

[ComodoHacker]

Для XML давно есть XML Schema, для JSON сделали аналог — JSON Schema.

Comments

[mindgrow]

Прочитайте что я написал под заголовком