🌐 Add Spanish translation of Tutorial - Path Parameters (#2219)

Co-authored-by: Pedro A. Moreno <[email protected]>
Co-authored-by: Sebastián Ramírez <[email protected]>

docs/es/docs/tutorial/path-params.md

@@ -0,0 +1,244 @@
+# Parámetros de path
+
+Puedes declarar los "parámetros" o "variables" con la misma sintaxis que usan los format strings de Python:
+
+```Python hl_lines="6-7"
+{!../../../docs_src/path_params/tutorial001.py!}
+```
+
+El valor del parámetro de path `item_id` será pasado a tu función como el argumento `item_id`.
+
+Entonces, si corres este ejemplo y vas a <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a>, verás una respuesta de:
+
+```JSON
+{"item_id":"foo"}
+```
+
+## Parámetros de path con tipos
+
+Puedes declarar el tipo de un parámetro de path en la función usando las anotaciones de tipos estándar de Python:
+
+```Python hl_lines="7"
+{!../../../docs_src/path_params/tutorial002.py!}
+```
+
+En este caso, `item_id` es declarado como un `int`.
+
+!!! check "Revisa"
+    Esto te dará soporte en el editor dentro de tu función, con chequeos de errores, autocompletado, etc.
+
+## <abbr title="también conocido en inglés como: serialization, parsing, marshalling">Conversión</abbr> de datos
+
+Si corres este ejemplo y abres tu navegador en <a href="http://127.0.0.1:8000/items/3" class="external-link" target="_blank">http://127.0.0.1:8000/items/3</a> verás una respuesta de:
+
+```JSON
+{"item_id":3}
+```
+
+!!! check "Revisa"
+    Observa que el valor que recibió (y devolvió) tu función es `3`, como un Python `int`, y no un string `"3"`.
+
+    Entonces, con esa declaración de tipos **FastAPI** te da <abbr title="convertir el string que viene de un HTTP request a datos de Python">"parsing"</abbr> automático del request.
+
+## Validación de datos
+
+Pero si abres tu navegador en <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a> verás este lindo error de HTTP:
+
+```JSON
+{
+    "detail": [
+        {
+            "loc": [
+                "path",
+                "item_id"
+            ],
+            "msg": "value is not a valid integer",
+            "type": "type_error.integer"
+        }
+    ]
+}
+```
+
+debido a que el parámetro de path `item_id` tenía el valor `"foo"`, que no es un `int`.
+
+El mismo error aparecería si pasaras un `float` en vez de un `int` como en: <a href="http://127.0.0.1:8000/items/4.2" class="external-link" target="_blank">http://127.0.0.1:8000/items/4.2</a>
+
+!!! check "Revisa"
+    Así, con la misma declaración de tipo de Python, **FastAPI** te da validación de datos.
+
+    Observa que el error también muestra claramente el punto exacto en el que no pasó la validación.
+
+    Esto es increíblemente útil cuando estás desarrollando y debugging código que interactúa con tu API.
+
+## Documentación
+
+Cuando abras tu navegador en <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a> verás la documentación automática e interactiva del API como:
+
+<img src="/img/tutorial/path-params/image01.png">
+
+!!! check "Revisa"
+    Nuevamente, con la misma declaración de tipo de Python, **FastAPI** te da documentación automática e interactiva (integrándose con Swagger UI)
+
+    Observa que el parámetro de path está declarado como un integer.
+
+## Beneficios basados en estándares, documentación alternativa
+
+Debido a que el schema generado es del estándar <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md" class="external-link" target="_blank">OpenAPI</a> hay muchas herramientas compatibles.
+
+Es por esto que **FastAPI** mismo provee una documentación alternativa de la API (usando ReDoc), a la que puedes acceder en <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>:
+
+<img src="/img/tutorial/path-params/image02.png">
+
+De la misma manera hay muchas herramientas compatibles. Incluyendo herramientas de generación de código para muchos lenguajes.
+
+## Pydantic
+
+Toda la validación de datos es realizada tras bastidores por <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>, así que obtienes todos sus beneficios. Así sabes que estás en buenas manos.
+
+Puedes usar las mismas declaraciones de tipos con `str`, `float`, `bool` y otros tipos de datos más complejos.
+
+Exploraremos varios de estos tipos en los próximos capítulos del tutorial.
+
+## El orden importa
+
+Cuando creas *operaciones de path* puedes encontrarte con situaciones en las que tengas un path fijo.
+
+Digamos algo como `/users/me` que sea para obtener datos del usuario actual.
+
+... y luego puedes tener el path `/users/{user_id}` para obtener los datos sobre un usuario específico asociados a un ID de usuario.
+
+Porque las *operaciones de path* son evaluadas en orden, tienes que asegurarte de que el path para `/users/me` sea declarado antes que el path para `/users/{user_id}`:
+
+```Python hl_lines="6  11"
+{!../../../docs_src/path_params/tutorial003.py!}
+```
+
+De otra manera el path para `/users/{user_id}` coincidiría también con `/users/me` "pensando" que está recibiendo el parámetro `user_id` con el valor `"me"`.
+
+## Valores predefinidos
+
+Si tienes una *operación de path* que recibe un *parámetro de path* pero quieres que los valores posibles del *parámetro de path* sean predefinidos puedes usar un <abbr title="Enumeration">`Enum`</abbr> estándar de Python.
+
+### Crea una clase `Enum`
+
+Importa `Enum` y crea una sub-clase que herede desde `str` y desde `Enum`.
+
+Al heredar desde `str` la documentación de la API podrá saber que los valores deben ser de tipo `string` y podrá mostrarlos correctamente.
+
+Luego crea atributos de clase con valores fijos, que serán los valores disponibles válidos:
+
+```Python hl_lines="1  6-9"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+!!! info "Información"
+    Las <a href="https://docs.python.org/3/library/enum.html" class="external-link" target="_blank">Enumerations (o enums) están disponibles en Python</a> desde la versión 3.4.
+
+!!! tip "Consejo"
+    Si lo estás dudando, "AlexNet", "ResNet", y "LeNet" son solo nombres de <abbr title="Tecnicamente, arquitecturas de modelos de Deep Learning">modelos</abbr> de Machine Learning.
+
+### Declara un *parámetro de path*
+
+Luego, crea un *parámetro de path* con anotaciones de tipos usando la clase enum que creaste (`ModelName`):
+
+```Python hl_lines="16"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+### Revisa la documentación
+
+Debido a que los valores disponibles para el *parámetro de path* están predefinidos, la documentación interactiva los puede mostrar bien:
+
+<img src="/img/tutorial/path-params/image03.png">
+
+### Trabajando con los *enumerations* de Python
+
+El valor del *parámetro de path* será un *enumeration member*.
+
+#### Compara *enumeration members*
+
+Puedes compararlo con el *enumeration member* en el enum (`ModelName`) que creaste:
+
+```Python hl_lines="17"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+#### Obtén el *enumeration value*
+
+Puedes obtener el valor exacto (un `str` en este caso) usando `model_name.value`, o en general, `your_enum_member.value`:
+
+```Python hl_lines="20"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+!!! tip "Consejo"
+    También podrías obtener el valor `"lenet"` con `ModelName.lenet.value`.
+
+#### Devuelve *enumeration members*
+
+Puedes devolver *enum members* desde tu *operación de path* inclusive en un body de JSON anidado (por ejemplo, un `dict`).
+
+Ellos serán convertidos a sus valores correspondientes (strings en este caso) antes de devolverlos al cliente:
+
+```Python hl_lines="18  21  23"
+{!../../../docs_src/path_params/tutorial005.py!}
+```
+
+En tu cliente obtendrás una respuesta en JSON como:
+
+```JSON
+{
+  "model_name": "alexnet",
+  "message": "Deep Learning FTW!"
+}
+```
+
+## Parámetros de path parameters que contienen paths
+
+Digamos que tienes una *operación de path* con un path `/files/{file_path}`.
+
+Pero necesitas que el mismo `file_path` contenga un path como `home/johndoe/myfile.txt`.
+
+Entonces, la URL para ese archivo sería algo como: `/files/home/johndoe/myfile.txt`.
+
+### Soporte de OpenAPI
+
+OpenAPI no soporta una manera de declarar un *parámetro de path* que contenga un path, dado que esto podría llevar a escenarios que son difíciles de probar y definir.
+
+Sin embargo, lo puedes hacer en **FastAPI** usando una de las herramientas internas de Starlette.
+
+La documentación seguirá funcionando, aunque no añadirá ninguna información diciendo que el parámetro debería contener un path.
+
+### Convertidor de path
+
+Usando una opción directamente desde Starlette puedes declarar un *parámetro de path* que contenga un path usando una URL como:
+
+```
+/files/{file_path:path}
+```
+
+En este caso el nombre del parámetro es `file_path` y la última parte, `:path`, le dice que el parámetro debería coincidir con cualquier path.
+
+Entonces lo puedes usar con:
+
+```Python hl_lines="6"
+{!../../../docs_src/path_params/tutorial004.py!}
+```
+
+!!! tip "Consejo"
+    Podrías necesitar que el parámetro contenga `/home/johndoe/myfile.txt` con un slash inicial (`/`).
+
+    En este caso la URL sería `/files//home/johndoe/myfile.txt` con un slash doble (`//`) entre `files` y `home`.
+
+## Repaso
+
+Con **FastAPI**, usando declaraciones de tipo de Python intuitivas y estándares, obtienes:
+
+* Soporte en el editor: chequeos de errores, auto-completado, etc.
+* "<abbr title="convertir el string que viene de un HTTP request a datos de Python">Parsing</abbr>" de datos
+* Validación de datos
+* Anotación de la API y documentación automática
+
+Solo tienes que declararlos una vez.
+
+Esa es probablemente la principal ventaja visible de **FastAPI**  sobre otros frameworks alternativos (aparte del rendimiento puro).

docs/es/mkdocs.yml

@@ -56,6 +56,7 @@ nav:
 - Tutorial - Guía de Usuario:
   - tutorial/index.md
   - tutorial/first-steps.md
+  - tutorial/path-params.md
 - Guía de Usuario Avanzada:
   - advanced/index.md
 - async.md