Применение JSON-Schema в тестировании и документировании API

[Arterius]

Как и сказал habrahabr.ru/post/185140/#comment_6438338. Теперь чищу монитор и клаву.

[Dreddik]

Проявите уважение, Боромир погиб смертью храбрых!

[dizews]

Спасибо за статью.
— как я понял, вы создаете json-schema во время написания тестов, тоесть поддержка актуальности самой схемы напрямую зависит от того, на сколько хорошо поддерживаются тесты?
— а невозникало мысли генерировать json-schema из валидаторов запросов?

[AotD]

Json-схема создается после/до написания функционала, она сама по себе — функциональный тест.
По ней как раз происходит валидация данных и по ней же строится документация (Объект такой-то содержит поля такие-то и включает объекты такие-то)

Эдакая круговая порука:
— Если после изменений кода валится валидация — проверь свой код.
— Если изменил формат выдачи — поменяй схему, а то валидацию не пройдет и дока устареет.

[web4_0]

После доклада внедрил JSON-schema у нас в API и сделал тесты в Jenkins. Кстати, помогло найти несколько багов в основном коде и выявить невалидные данные в поиске. Так что спасибо за доклад. И привет вашему начальнику тестирования.

[burivuh]

Буквально неделю назад прикрутили у себя валидацию данных, приходящих с клиентских приложений на сервер, с помощью JSON-schema. Сделали логирование ошибок в данных в сентри, оказалось более 10 ошибок в несложном объекте. Короче, крайне рекомендую.

[Azy]

Что юзали для питона?

[burivuh]

github.com/Julian/jsonschema вот эту штуку вроде

[barbuza]

это как то совсем не python way
посмотрите на github.com/barbuza/contract/blob/master/contract.py и на форки

[mahnunchik]

Не могу не порекомендовать отличную JS библиотеку валидации, на которую сам недавно наткнулся:
github.com/geraintluff/tv4

Работает и на клиенте и на сервере.
Активно развивается.

Правда поддерживает только 4 версию «JSON Schema».

[Athari]

Реализации формата JSON-Schema есть для разных языков. Как видно, выбор не велик. Для PHP две библиотеки от двух институтов: MIT и Berkeley.

Там лицензии BSD и MIT, а не творчество Berkley и MIT. Одно «Copyright © 2008, Gradua Networks; Author: Bruno Prieto Reis», другое «Copyright © 2011 Harold Asbridge». Почему на сайте JSON Schema вместо «BSD» написали «Berkley» — вопрос к ним.

[len]

Сергей, спасибо за статью.

И сразу вопрос.
В документации к всевозможным API, известное дело, присутствует не только информация об ответе, но и информация о запросе. Запрос (URI, тип, параметры, ...) вы тоже с помощью JSON Schema описываете, или как-то иначе?
И, да, хотелось бы увидеть (если это не секрет) пример схемы для реального запроса.

Что касается библиотек и поддержки языков, могу заметить, что реализовать свой собственный валидатор JSON Schema (возможно, включив в него какие-то специфические штуки) не составляет особого труда. Так что, пожалуй, используя почти любой язык, можно смело брать JSON Schema как полезную штуку для документации/валидации/еще каких-то вещей.

[ks7it]

JSON схемы мы используем только для ответов API. И только потому, что API запросы у нас очень простые. В них нет иерархических структур. Валидация происходит на стороне приложения. А для документирования запросов через JSON схемы просто руки не доходят, профита будет не очень много.

На счет собственной реализации согласен. Принципальных сложностей в создании валидатора JSON схем нет. Было бы время и желание.

[len]

Ага! А что насчет реального примера? ;)
Интересует как раз кейс, когда параметр в ответе может принимать, например, и целочисленные значения, и null. Как это будет выглядеть в схеме?

[AotD]

Перечисление типов никто не отменял:

{
    "type": ["string", "null"]
    ...
}

Или для объектов:

{
    "type": ["object", "null"],
    "header": "Какой-то вложенный объект",
    "required": true,
    "properties": {
        "id": {
            "type": "integer",
            "required": true,
         },
       ...
    }
}

В последнем примере либо поле существует и null, либо в нем лежит какая-то структура, которая будет валидироваться согласно properties

[len]

Ага, спасибо. У меня почему-то валидатор (jsv4-php) падал при попытке так написать. Но, видимо, дело было в чем-то другом :)

[AotD]

tools.ietf.org/html/draft-zyp-json-schema-03#section-5.1

[champ]

А почему бы не опубликовать JSON schema вместе с API? Это сослужило бы пользу разработчикам, его использующим.