Workshop práctico de governance automatizado de APIs
Yo usé homebrew para instalar nvm
brew install nvm
Las opciones para instalarlo en sus distibuciones de OS las pueden encontrar acá: https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/
Yo usé colima para docker
brew install colima
Las opciones para instalarlo en sus distibuciones de OS las pueden encontrar acá: https://github.com/abiosoft/colima/blob/main/docs/INSTALL.md
Yo usé homebrew para instalar pyenv
brew install pyenv
Las opciones para instalarlo en sus distibuciones de OS las pueden encontrar acá: https://github.com/pyenv/pyenv
Yo usaré VS Code para mostrar el código
colima start
docker pull swaggerapi/swagger-editor:latest
docker run -d -p 80:8080 swaggerapi/swagger-editor:latest
Abrir en el browser http://localhost/
Dar clic en File > Save as YAML e incluir este archivo en su repo
nvm use --lts
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
touch .spectral.yaml
spectral lint openapi.yaml
extends: ["spectral:oas"]
Spectral tiene sets de reglas predefinidos que podemos utilizar como el que incluimos. Más información del set que incluimos se encuentra acá: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules
spectral lint openapi.yaml
Acá dediquemos un tiempo para entender los warnings. Incluso pueden ver en su IDE si se muestran los warnings.
"overrides": [
{
"files": ["openapi.yaml"],
"rules": {
"operation-description": "off"
}
}
]
Y una vez mas volvamos a ejecutar el cli
spectral lint openapi.yaml
rules:
x-domainInfo:
description: Info object must have "x-domainInfo"
given: $.info
severity: error
then:
- field: x-domainInfo
function: truthy
x-domainInfo:
someField: some value
Y una vez mas volvamos a ejecutar el cli
spectral lint openapi.yaml
Paso 11 - Definamos una segunda regla que especifique campos deben existir relacionados al dominio en .spectral.yaml
Dentro de rules, debajo de la regla anteriormente creada incluir:
x-domainInfo-fields:
description: Custom domain properties object must have "domainName" and "subdomainName" fields
given: $.info.x-domainInfo
severity: error
then:
- field: domainName
function: truthy
- field: subdomainName
function: truthy
Y una vez mas volvamos a ejecutar el cli
spectral lint openapi.yaml
x-domainInfo:
domainName: some value
subdomainName: some value
Y una vez mas volvamos a ejecutar el cli
spectral lint openapi.yaml
Acá dediquemos primero un tiempo para revisar el Business Capability Map que usaremos de ejemplo (en las diapositivas) para entender mejor la regla
Dentro de rules, debajo de la regla anteriormente creada incluir:
valid-domainName:
description: Property "domainName"should have a valid value
given: $.info.x-domainInfo
severity: error
then:
- field: domainName
function: enumeration
functionOptions:
values:
- customer-services-management
- staff-and-personnel-management
- airflight-management
- supporting-services-management
Y una vez mas volvamos a ejecutar el cli
spectral lint openapi.yaml
x-domainInfo:
domainName: customer-services-management
subdomainName: some value
Y una vez mas volvamos a ejecutar el cli
spectral lint openapi.yaml
De esta manera podemos seguir iterando sobre las reglas que refelejen la necesidad de esta organización
pyenv install 3.10
pyenv local 3.10
pyenv version
pip install --upgrade pip
pip install cookiecutter
{
"api_name": "api-name",
"api_description": "Breve descripción de la API",
"domain_name": "customer-services-management"
}
mkdir {{cookiecutter.api_name}}
Mover los archivos .spectral.yaml y openapi.yaml a esta carpeta y copiar el archivo .gitignore
mv .spectral.yaml \{\{cookiecutter.api_name\}\}
mv openapi.yaml \{\{cookiecutter.api_name\}\}
cp .gitignore \{\{cookiecutter.api_name\}\}
title: Swagger {{cookiecutter.api_name}} - OpenAPI 3.0
domainName: {{cookiecutter.domain_name}}
cd \{\{cookiecutter.api_name\}\}
touch README.md
Y colocar una estructura base de README para una nueva API siguiendo el paradigma API First
# {{cookiecutter.api_name}}
{{cookiecutter.api_description}}
## Dependencias
Para validar de manera local la especificación de la API es necesario contar con npm, para ello es recomendable usar un manejador de versiones de Node como es nvm
### nvm
Instalar nvm (por ejemplo usando homebrew)
`brew install nvm`
Otras opciones de instalación las pueden encontrar acá: https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/
## Validación de la especificación de la API
## Instalar spectral-cli
`nvm use --lts`
`npm install -g @stoplight/spectral-cli`
## Ejecutar el cli para analizar openapi.yaml
`spectral lint openapi.yaml`
cd ../..
cookiecutter api-practical-governance/
Revisar el resultado de la carpeta generada en base al template
https://github.com/swagger-api/swagger-editor https://editor-next.swagger.io/ https://stoplight.io/open-source/spectral https://cookiecutter.readthedocs.io/en/stable/index.html
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent