Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
API Blueprint
Search
Sponsored
·
Ship Features Fearlessly
Turn features on and off without deploys. Used by thousands of Ruby developers.
→
Dmitry Efimov
September 07, 2016
Programming
93
0
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
API Blueprint
Tools
Dmitry Efimov
September 07, 2016
Transcript
38 slides
API Blueprint
типичная документация по API = route + json
типичная документация на API Blueprint = AST Markdown + MSON
JSON-SCHEMA
Рассмотрим на примере самого простого микросервиса
требуемый функционал Request: curl -v -X GET http://localhost:3000/status Response: <
HTTP/1.1 200 OK
документация API = route + json
исходный текст в API Blueprint # Микросервис ## Статус [/status]
### Проверить [GET] Узнать статус микросервиса + Request + Response 200
Tools • Editors •Parsers •Renders •Testing •Mock servers •Others
apiary.io
apiary.io
apiary.io
Atom editor language
Vim, Emacs, Visual Studio Code
Tools •Editors • Parsers •Renders •Testing •Mock servers •Others
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
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
gem redsnow
Tools •Editors •Parsers • Renders •Testing •Mock servers •Others
любой Markdown preview
Aglio aglio -i doc.apib -s (default localtosh:3000)
Aglio aglio -i doc.apib -s --theme-template triple (default localtosh:3000)
Aglio aglio -i doc.apib -s --theme-variables slate (default localtosh:3000)
Iglo(go), Atom preview
Tools •Editors •Parsers •Renders • Testing •Mock servers •Others
Dredd если на самом деле есть приложение и документация на
него, и хочется проверить только один первый ответ в документации для каждого запроса который обязательно не возвращает тело dredd doc.apib http://localhost:3000
Dredd
Dredd
где пригодятся такие авто тесты?
Tools •Editors •Parsers •Renders •Testing • Mock servers •Others
Drakov если хочется сделать мок сервер для запросов которые не
отправляют тело запроса и возвращают код ответа без тела ответа drakov -f doc.apib curl -v -X GET http://localhost:3000/status
Drakov
Можно “натравить” dredd на drakov используя одну и туже документацию
и они оба отработают корректно (если документация валидна)
gem apib-mock_server
зачем нужны такие mock сервера?
Tools •Editors •Parsers •Renders •Testing •Mock servers • Others
Ни один инструмент не использует MSON(и даже просто JSON) (не
считая парсер и превью)
Middleware валидация
конец
More Decks by Dmitry Efimov
See All by Dmitry Efimov
Автоматизируем синхронизацию HTTP API и документации
tuwilof
0
55
Автоматизация Document-Driven Development для проектов с большим API
tuwilof
0
55
Инструменты для обнаружения рассинхронизации реализации “REST” API от документации
tuwilof
0
62
Валидация “REST” API по документации APIB
tuwilof
0
70
Негативное тестирование “REST” API и защита от него
tuwilof
0
350
Ликбез по JSON
tuwilof
0
98
Документирование API
tuwilof
0
210
Почему и как заменить все id на UUID
tuwilof
0
110
Authentication in rails. Monolith vs SPA
tuwilof
0
220
Other Decks in Programming
See All in Programming
Growing PicoRuby's Ecosystem on ESP32
yuuu
2
150
선언형 햅틱 라이브러리 진동을 소개합니다
l2hyunwoo
1
330
眠らない開発チームの作り方
biwakonbu
0
100
高橋メソッドでCVE解説シリーズ 〜CVE-2026-112816〜
hakkadaikon
0
270
Augmenting AI with the Power of Jakarta EE
ivargrimstad
0
420
Scalaの型でマルチテナントの認可を守る
nextbeatdev
0
180
DroidKnights 2026 Android A2UI Jetpack Compose 기반의 안전한 AI UI 렌더링 - 박제창
itsmedreamwalker
1
260
あなたはMCPの機能を、まだ知らない。
4geru
1
740
テストだけで見つかる? Rubyでつくるメソッド発掘器
izawa
0
160
Augmenting AI with the Power of Jakarta EE
ivargrimstad
0
120
The Cost of the DOM
ypresto
2
200
仕様駆動開発入門 (何を作るかを先に決めて渡す) | 目指せ Kiro マスター 05
inariku
PRO
3
220
Featured
See All Featured
The Limits of Empathy - UXLibs8
cassininazir
2
800
VelocityConf: Rendering Performance Case Studies
addyosmani
331
25k
Rebuilding a faster, lazier Slack
samanthasiow
85
9.8k
The Hidden Cost of Media on the Web [PixelPalooza 2025]
tammyeverts
2
580
Connecting the Dots Between Site Speed, User Experience & Your Business [WebExpo 2025]
tammyeverts
11
1.1k
How to Ace a Technical Interview
jacobian
280
24k
Efficient Content Optimization with Google Search Console & Apps Script
katarinadahlin
PRO
1
1k
Balancing Empowerment & Direction
lara
6
1.4k
世界の人気アプリ100個を分析して見えたペイウォール設計の心得
akihiro_kokubo
PRO
73
43k
Hiding What from Whom? A Critical Review of the History of Programming languages for Music
tomoyanonymous
3
1.5k
GraphQLとの向き合い方2022年版
quramy
50
15k
The Curious Case for Waylosing
cassininazir
1
630