Автоматизируем синхронизацию HTTP API и документации

Transcript

2. Когда я был джуном, пришёл тимлид, принёс инструмент 2
3. Дмитрий Ефимов Работаю бэкенд-разработчиком в FunBox. Девлид Ruby-команды. Пишу веб на Ruby более 5 лет. ВЕЩАЕТ СВЯЗАТЬСЯ СО МНОЙ vk.com/tuwilof @tuwilof facebook.com/tuwilof instagram.com/tuwilof 3 github.com/tuwilof twitter.com/tuwilof
4. FunBox Более 13 лет мы разрабатываем решения для сотовых операторов на Ruby, Ruby on Rails, Erlang, Elixir, Python. О КОМПАНИИ МЫ В СОЦСЕТЯХ twitter.com/funbox_team youtube.com/funboxteam 4 github.com/funbox instagram.com/funboxteam facebook.com/funboxteam funbox.ru
5. Надо написать API 5
6. Как упростить себе жизнь? 6
7. Глава I. Снизу вверх Глава II. Сверху вниз Глава III. Независимость
8. Глава I Снизу вверх Генерация документации из кода
9. Не совсем из кода – Комментарии – Тесты 9
10. Из комментариев 10
11. apipie-rails 11 class Api::SessionsController < Api::ApplicationController resource_description do name "Аутентификация" end api! 'Вход в систему' param: login, String, required: true, desc: "Логин пользователя" param: password, String, required: true, desc: "Пароль пользователя" error 401, "Ошибка в логине или пароле" example 'можно написать пример тела запроса или ответа' def create … end end
12. Плюсы + Комментарии + Дока рядом с кодом 12
13. Плюсы, но ещё и минусы + Комментарии + Дока рядом с кодом 13 – Комментарии – Ручное дублирование
14. Из тестов 14
15. rspec_api_documentation 15 require 'rails_helper' require 'rspec_api_documentation/dsl' resource "Orders" do get "/orders" do example "Listing orders" do do_request expect(status).to eq 200 end end end
16. Плюсы + Не надо писать документацию + В документации то же самое, что и в тестах 16
17. Плюсы, но ещё и минусы + Не надо писать документацию + В документации то же самое, что и в тестах 17 – Надо начинать с тестов – Много JSON’ов
18. 18 Когда QA стали ставить баги на негативные кейсы
19. – Не такая уж генерация – Следить за типами 19
20. Глава II Сверху вниз Генерация кода из документации
21. Documentation-Driven Development Не путать с Domain-Driven Design 21
22. GraphQL и компания 22
25. Плюсы + Не REST + Не надо писать валидацию 25
26. Плюсы, но ещё и минусы + Не REST + Не надо писать валидацию 26 – Не REST – Сложнее оптимизация – Выше порог поддержки – Выше порог тестирования – Всё равно нужно тащить сгенерированный клиент
27. Глава III Независимость Путь без генерации
28. Если не генерировать, работы будет больше? 28
29. 29 Работы будет меньше без кода
30. Документация >= Код 30
31. Документация >= Код – Hyper-Schema – OpenAPI 2 и OpenAPI 3 (Swagger) – API Blueprint и другие 31
32. Если отбросить синтаксический сахар 32
33. [ { "path": "/sessions", "method": "POST", "content-type": "application/json", "requests": [query string and body X], "responses": [ { "status": "401", "content-type": "application/json", "body": {} }, { "status": "429", "content-type": "application/json", "body": {} }, { "status": "201", "content-type": "application/json", "body": X } ] } ] 33
34. [ { "path": "/sessions", "method": "POST", "content-type": "application/json", "requests": [query string and body X], "responses": [ { "status": "401", "content-type": "application/json", "body": {} }, { "status": "429", "content-type": "application/json", "body": {} }, { "status": "201", "content-type": "application/json", "body": X } ] } ] 34
35. [ { "path": "/sessions", "method": "POST", "content-type": "application/json", "requests": [query string and body X], "responses": [ { "status": "401", "content-type": "application/json", "body": {} }, { "status": "429", "content-type": "application/json", "body": {} }, { "status": "201", "content-type": "application/json", "body": X } ] } ] 35
36. [ { "path": "/sessions", "method": "POST", "content-type": "application/json", "requests": [query string and body X], "responses": [ { "status": "401", "content-type": "application/json", "body": {} }, { "status": "429", "content-type": "application/json", "body": {} }, { "status": "201", "content-type": "application/json", "body": X } ] } ] 36
37. [ { "path": "/sessions", "method": "POST", "content-type": "application/json", "requests": [query string and body X], "responses": [ { "status": "401", "content-type": "application/json", "body": {} }, { "status": "429", "content-type": "application/json", "body": {} }, { "status": "201", "content-type": "application/json", "body": X } ] } ] 37
39. JSON { "name": "John" } JSON-SCHEMA { "properties": { "name": { "type": "string" } } } 39
40. JSON { "kind": "book" }, { "kind": "magazine" } JSON-SCHEMA { "properties": { "kind": { "type": "string", "enum": [ "book", "magazine"] } } "required": ["kind"] } 40
41. JSON Schema Validator 41
42. Валидация входящих запросов 42 github.com/interagent/committee github.com/funbox/esplanade github.com/funbox/plumbapius Ruby Erlang/Elixir
43. Documentation Like Firewall 43
44. Middleware 44
45. class YourMiddleware def initialize(app) @app = app end def call(env) status, headers, body = @app.call(env) [status, headers, body] rescue Esplanade::Request::NotDocumented [ 200, {'Content-Type' => 'application/json; charset=utf-8'}, [{status: :incorrectRequest, error: :requestNotDocumented}.to_json] ] rescue Esplanade::Request::BodyIsNotJson [ 200, {'Content-Type' => 'application/json; charset=utf-8'}, [{status: :incorrectRequest, error: :requestBodyIsNotJson}.to_json] ] rescue Esplanade::Request::Invalid => e [ 200, {'Content-Type' => 'application/json; charset=utf-8'}, [{status: :incorrectRequest, error: :requestBodylsInvalid, details: e}.to_json] ] end end 45
46. Документация >= Тесты 46
47. RSpec Matchers 47 github.com/westfieldlabs/apivore github.com/square/fdoc github.com/funbox/fitting
48. Тесты — это хорошо, но лучше посмотреть покрытие документации тестами и тестов документацией 48
49. Join 49 Тесты Документация
50. Join 50 Тесты Документация Не задокументированы Не реализована Идеально
51. Fully conforming requests: DELETE /api/v1/book 200 201 404 DELETE /api/v1/book/{id} 200 201 404 GET /api/v1/book/{id}/seller 200 201 404 Partially conforming requests: GET /api/v1/book 200 404 POST /api/v1/book 200 201 404 GET /api/v1/book/{id} 200 404 200 PATCH /api/v1/book/{id} 200 201 404 Non-conforming requests: GET /api/v1/seller 200 201 404 GET /api/v1/buyer 200 404 API requests with fully implemented responses: 3 (33.33% of 9). API requests with partially implemented responses: 4 (44.44% of 9). API requests with no implemented responses: 2 (22.22% of 9). API responses conforming to the blueprint: 16 (64.00% of 25). API responses with validation errors or untested: 9 (36.00% of 25). 51
52. [ { "method": "GET", "path": "/api/v1/book", "body": {}, "response": { "status": 200, "body": { "title": "The Martian Chronicles" } }, "title": "/spec/controllers/api/v1/books_controller_spec.rb:11", "group": "/spec/controllers/api/v1/books_controller_spec.rb" }, { "method": "POST", "path": "/api/v1/book", "body": {}, "response": { "status": 200, "body": { "title": "The Old Man and the Sea" } }, "title": "/spec/controllers/api/v1/books_controller_spec.rb:22", "group": "/spec/controllers/api/v1/books_controller_spec.rb" } ] 52
53. prefixes 53 /api/v1 /api/v2 /api/admin
55. actions 55 METHOD PATH POST /api/v1/books GET /api/v1/books DELETE /api/v1/books
57. responses 57 STATUS CONTENT-TYPE BODY 200 "application/json" {"name": "War and Peace"}
59. Пошли дальше 59
60. JSON Shema >= Валидация 60
61. Одна json-schema может быть несколькими json-schema’ми 61
63. Несмотря на достигнутое, многое впереди 63
64. Выводы – Подходов много, рассмотри все – API и документацию можно синхронизировать без генерации 64
65. Дмитрий Ефимов twitter.com/tuwilof instagram.com/tuwilof FunBox twitter.com/funbox_team @tuwilof funbox.ru Спасибо за внимание youtube.com/funboxteam