API Blueprint

Tools

Transcript

1. API Blueprint
2. типичная документация по API = route + json
3. типичная документация на API Blueprint = AST Markdown + MSON JSON-SCHEMA
4. Рассмотрим на примере самого простого микросервиса
5. требуемый функционал Request: curl -v -X GET http://localhost:3000/status Response: < HTTP/1.1 200 OK
6. документация API = route + json
7. исходный текст в API Blueprint # Микросервис ## Статус [/status] ### Проверить [GET] Узнать статус микросервиса + Request + Response 200
8. Tools • Editors •Parsers •Renders •Testing •Mock servers •Others
9. apiary.io
10. apiary.io
11. apiary.io
12. Atom editor language
13. Vim, Emacs, Visual Studio Code
14. Tools •Editors • Parsers •Renders •Testing •Mock servers •Others
15. Drafter drafter doc.apib (default YAML) element: "parseResult" content: - element: "category" meta: classes: - "api" title: "Микросервис" content: - element: "category" meta: classes: - "resourceGroup" title: "" content: - element: "resource" meta: title: "Статус" attributes: href: "/status" content: - element: "transition" meta: title: "Проверить" content: - element: "copy" content: "Узнать статус микросервиса\n" - element: "httpTransaction" content: - element: "httpRequest" attributes: method: "GET" content: [] - element: "httpResponse" attributes: statusCode: "200" content: [] - element: "annotation" meta: classes: - "warning" attributes: code: 6 sourceMap: - element: "sourceMap" content: - - 81 - 10 content: "empty request message-body" OK. warning: (6) empty request message-body :81:10
16. drafter doc.apib --format json {"element"=>"parseResult", "content"=>[{"element"=>"category", "meta"=>{"classes"=>["api"], "title"=>"Микросервис"}, "content"=>[{"element"=>"category", "meta"=>{"classes"=>["resourceGroup"], "title"=>""}, "content"=>[{"element"=>"resource", "meta"=>{"title"=>"Статус"}, "attributes"=>{"href"=>"/status"}, "content"=>[{"element"=>"transition", "meta"=>{"title"=>"Проверить"}, "content"=>[{"element"=>"copy", "content"=>"Узнать статус микросервиса\n"}, {"element"=>"httpTransaction", "content"=>[{"element"=>"httpRequest", "attributes"=>{"method"=>"GET"}, "content"=>[]}, {"element"=>"httpResponse", "attributes"=>{"statusCode"=>"200"}, "content"=>[]}]}]}]}]}]}, {"element"=>"annotation", "meta"=>{"classes"=>["warning"]}, "attributes"=>{"code"=>6, "sourceMap"=>[{"element"=>"sourceMap", "content"=>[[81, 10]]}]}, "content"=>"empty request message-body”}]} OK. warning: (6) empty request message-body :81:10
17. gem redsnow
18. Tools •Editors •Parsers • Renders •Testing •Mock servers •Others
19. любой Markdown preview
20. Aglio aglio -i doc.apib -s (default localtosh:3000)
21. Aglio aglio -i doc.apib -s --theme-template triple (default localtosh:3000)
22. Aglio aglio -i doc.apib -s --theme-variables slate (default localtosh:3000)
23. Iglo(go), Atom preview
24. Tools •Editors •Parsers •Renders • Testing •Mock servers •Others
25. Dredd если на самом деле есть приложение и документация на него, и хочется проверить только один первый ответ в документации для каждого запроса который обязательно не возвращает тело dredd doc.apib http://localhost:3000
26. Dredd
27. Dredd
28. где пригодятся такие авто тесты?
29. Tools •Editors •Parsers •Renders •Testing • Mock servers •Others
30. Drakov если хочется сделать мок сервер для запросов которые не отправляют тело запроса и возвращают код ответа без тела ответа drakov -f doc.apib curl -v -X GET http://localhost:3000/status
31. Drakov
32. Можно “натравить” dredd на drakov используя одну и туже документацию и они оба отработают корректно (если документация валидна)
33. gem apib-mock_server
34. зачем нужны такие mock сервера?
35. Tools •Editors •Parsers •Renders •Testing •Mock servers • Others
36. Ни один инструмент не использует MSON(и даже просто JSON) (не считая парсер и превью)
37. Middleware валидация
38. конец