nodejs/nodebestpractices
1
0
Fork 0
mirror of https://github.com/goldbergyoni/nodebestpractices.git synced 2025-10-27 19:17:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

documentingusingswagger

Browse Source 
Signed-off-by: Alexander Ivanov <oshli.a.er@gmail.com>
This commit is contained in:
Alexander Ivanov
2019-07-20 12:18:36 +03:00
parent a255c38fdc
commit 53f366e36f
2 changed files with 53 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.russian.md
View File

@ -158,7 +158,7 @@
**Иначе:** Клиент API может принять решение о сбое и перезапуске только потому, что он получил ошибку, которую он не может понять. Примечание: вызывающим абонентом вашего API можете быть и вы сами (очень типично для микросервисной среды)
🔗 [**Подробнее: документирование ошибок API в Swagger или GraphQL**](/sections/errorhandling/documentingusingswagger.md)
🔗 [**Подробнее: документирование ошибок API в Swagger или GraphQL**](/sections/errorhandling/documentingusingswagger.russian.md)
<br/><br/>

52
sections/errorhandling/documentingusingswagger.russian.md Normal file
View File

@ -0,0 +1,52 @@
# Документироваие ошибок API при использовании Swagger или GraphQL
### Объяснение в один абзац
API-интерфейсы REST возвращают результаты с использованием кодов состояния HTTP, поэтому пользователь API должен знать не только о схеме API, но и о возможных ошибках - вызывающий может затем поймать ошибку и тактично ее обработать. Например, в документации по API может быть заранее указано, что HTTP-статус 409 возвращается, когда имя клиента уже существует (при условии, что API регистрирует новых пользователей), поэтому вызывающая сторона может соответственно отобразить лучший UX для данной ситуации. Swagger - это стандарт, определяющий схему документации API, предлагающую эко-систему инструментов, позволяющую легко создавать документацию в Интернете, см. экраны печати ниже.
Если вы уже приняли GraphQL для своих конечных точек API, ваша схема уже содержит строгие гарантии того, как должны выглядеть ошибки ([описано в спецификации](https://facebook.github.io/graphql/June2018/#sec-Errors )) и как они должны обрабатываться вашими инструментами на стороне клиента. Кроме того, вы также можете дополнить их документацией на основе комментариев.
### Пример ошибки GraphQL
> В этом примере используется [SWAPI](https://graphql.org/swapi-graphql), API-интерфейс Star Wars.
```graphql
# should fail because id is not valid
{
film(id: "1ZmlsbXM6MQ==") {
title
}
}
```
```json
{
"errors": [
{
"message": "No entry in local cache for https://swapi.co/api/films/.../",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"film"
]
}
],
"data": {
"film": null
}
}
```
### Цитата блога: "Вы должны сообщить своим абонентам, какие ошибки могут произойти"
Из блога Joyent, занял 1 место по ключевым словам "Node.js logging"
> Мы говорили о том, как обрабатывать ошибки, но когда вы пишете новую функцию, как вы доставляете ошибки в код, вызвавший вашу функцию? … Если вы не знаете, какие ошибки могут произойти, или не знаете, что они означают, то ваша программа может быть исправлена ​​только случайно. Поэтому, если вы пишете новую функцию, вы должны сообщить своим абонентам, какие ошибки могут произойти и что они означают …
### Полезный инструмент: Swagger Online Documentation Creator
![Swagger API Scheme](https://github.com/i0natan/nodebestpractices/blob/master/assets/images/swaggerDoc.png "API error handling")