codegen arrogante
Swagger
Este es el proyecto Swagger Codegen, que permite la generación de bibliotecas de cliente API (generación de SDK), resguardos de servidor y documentación automáticamente dada una especificación OpenAPI.
Si desea contribuir, consulte las pautas y una lista de tareas abiertas.
Para obtener más información, consulte la página Wiki y las preguntas frecuentes.
⚠️ este documento hace referencia a la versión 2.X, consulte aquí para la 3.X.
Las líneas de versión 2.X y 3.X de Swagger Codegen están disponibles y se mantienen de forma independiente.
NOTAS:
Las versiones 2.X ( io.swagger ) y 3.X ( io.swagger.codegen.v3 ) tienen diferentes identificadores de grupo.
OpenAPI 3.0.X solo es compatible con la versión 3.X.
Para obtener información completa sobre versiones, consulte la documentación sobre versiones.
Actualmente, se admiten los siguientes lenguajes/marcos:
Clientes API : ActionScript , Ada , Apex , Bash , C# (.net 2.0, 3.5 o posterior), C++ (cpprest, Qt5, Tizen), Clojure , Dart , Elixir , Elm , Eiffel , Erlang , Go , Groovy , Haskell (http -cliente, sirviente), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Biblioteca cliente API de Google para Java, tenga la seguridad), Kotlin , Lua , Node.js (ES5, ES6, AngularJS con anotaciones del compilador de cierre de Google) Objective-C , Perl , PHP , PowerShell , Python , R , Ruby , Rust (óxido, servidor oxidado), Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typecript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Resguardos de servidor : Ada , C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang , Go , Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , Play Framework, PKMST), Kotlin , PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS , Ruby (Sinatra, Rails5), Rust (servidor de óxido), Scala (Finch, Lagom, Scalatra)
Generadores de documentación API : HTML , Confluence Wiki
Archivos de configuración : Apache2
Otros : JMeter
Consulte OpenAPI-Spec para obtener información adicional sobre el proyecto OpenAPI.
Versionado
Compatibilidad
Empezando
Generadores
Para generar una biblioteca cliente de muestra
Generando bibliotecas desde su servidor
Validando su especificación OpenAPI
Generando documentación API HTML dinámica
Generando documentación de API HTML estática
Integración del flujo de trabajo
Generadores en línea
Contribución
Equipo central de Swagger Codegen
La especificación OpenAPI ha pasado por 3 revisiones desde su creación inicial en 2010. Las versiones estables actuales del proyecto Swagger Codegen tienen las siguientes compatibilidades con la especificación OpenAPI:
| Versión Swagger Codegen | Fecha de lanzamiento | Compatibilidad con especificaciones Swagger/OpenAPI | Notas |
|---|---|---|---|
| 3.0.62 ( estable actual ) | 2024-08-27 | 1,0, 1,1, 1,2, 2,0, 3,0 | etiqueta v3.0.62 |
| 2.4.43 ( estable actual ) | 2024-08-09 | 1,0, 1,1, 1,2, 2,0 | etiqueta v2.4.42 |
Aquí también hay una descripción general de lo que se avecina a la vuelta de la esquina:
| Versión Swagger Codegen | Fecha de lanzamiento | Compatibilidad con especificaciones Swagger/OpenAPI | Notas |
|---|---|---|---|
| 3.0.63-SNAPSHOT (actual 3.0.0, próxima versión menor) SNAPSHOT | Por determinar | 1,0, 1,1, 1,2, 2,0, 3,0 | Lanzamiento menor |
| 2.4.44-SNAPSHOT (master actual, próxima versión menor) SNAPSHOT | Por determinar | 1,0, 1,1, 1,2, 2,0 | Lanzamiento menor |
Para obtener un desglose detallado de todas las versiones, consulte la lista de compatibilidad completa.
Para comenzar a utilizar Swagger Codegen, consulte las siguientes guías e instrucciones:
Requisitos previos
Edificio
Usando ventana acoplable
Una vez que haya configurado su entorno, estará listo para comenzar a generar clientes y/o servidores.
Como ejemplo rápido, para generar un cliente PHP para https://petstore.swagger.io/v2/swagger.json, puede ejecutar lo siguiente:
clon de git https://github.com/swagger-api/swagger-codegencd swagger-codegen
paquete limpio mvn
java -jar módulos/swagger-codegen-cli/target/swagger-codegen-cli.jar generar
-yo https://petstore.swagger.io/v2/swagger.json
-l php
-o /var/tmp/php_api_clientNota: si estás en Windows, reemplaza el último comando con
java -jar módulosswagger-codegen-clitargetswagger-codegen-cli.jar generar -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
También puede descargar el JAR (última versión) directamente desde maven.org
Para obtener una lista de opciones generales disponibles, puede ejecutar lo siguiente:
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar ayuda a generar
Para obtener una lista de las opciones especificadas de PHP (que se pueden pasar al generador con un archivo de configuración a través de la opción -c ), ejecute
java -jar módulos/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
Puede crear un cliente con la API de tienda de mascotas de muestra de swagger de la siguiente manera:
./bin/java-petstore.sh
(En Windows, ejecute .binwindowsjava-petstore.bat en su lugar)
Esto ejecutará el generador con este comando:
java -jar módulos/swagger-codegen-cli/target/swagger-codegen-cli.jar generar -yo https://petstore.swagger.io/v2/swagger.json -ljava -o muestras/cliente/petstore/java
con una serie de opciones. Puede obtener las opciones con el comando help generate (a continuación solo se muestran resultados parciales):
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a | --auth )]
[--additional-properties ...]
[--api-package ] [--artifact-id ]
[--artifact-version ]
[(-c | --config )]
[-D ...] [--git-repo-id ]
[--git-user-id ] [--group-id ]
[--http-user-agent ]
(-i | --input-spec )
[--ignore-file-override ]
[--import-mappings ...]
[--instantiation-types ...]
[--invoker-package ]
(-l | --lang )
[--language-specific-primitives ...]
[--library ] [--model-name-prefix ]
[--model-name-suffix ]
[--model-package ]
[(-o | --output )]
[--release-note ] [--remove-operation-id-prefix]
[--reserved-words-mappings ...]
[(-s | --skip-overwrite)]
[(-t | --template-dir )]
[--type-mappings ...] [(-v | --verbose)]
OPTIONS
-a , --auth
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
...... (results omitted)
-v, --verbose
verbose mode Luego puede compilar y ejecutar el cliente, así como realizar pruebas unitarias contra él:
muestras de cd/cliente/petstore/java paquete mvn
Otros idiomas también tienen muestras de tiendas de mascotas:
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
Es igual de fácil: simplemente use el indicador -i para señalar un servidor o un archivo.
? Swagger Codegen viene con una gran flexibilidad para respaldar sus preferencias de generación de código. Consulte la documentación de los generadores que le muestra algunas de las posibilidades y le muestra cómo generar a partir de archivos locales e ignorar los formatos de archivo.
Es posible que no desee generar todos los modelos en su proyecto. Del mismo modo, es posible que desee escribir sólo una o dos API. Si ese es el caso, consulte las instrucciones de generación selectiva.
Existen diferentes aspectos de la personalización del generador de código más allá de simplemente crear o modificar plantillas. Cada idioma tiene un archivo de configuración de soporte para manejar diferentes tipos de asignaciones o traer sus propios modelos. Para obtener más información, consulte los documentos de configuración avanzada.
Tienes opciones. Lo más fácil es utilizar nuestro validador en línea que no solo le permitirá validar su especificación, sino que con el indicador de depuración podrá ver qué está mal con su especificación. Por ejemplo, consulte Swagger Validator.
Si desea tener la validación directamente en su propia máquina, Spectral es una excelente opción.
Para hacerlo, simplemente use el indicador -l dynamic-html cuando lea un archivo de especificaciones. Esto crea documentación HTML que está disponible como una aplicación de una sola página con AJAX. Para ver la documentación:
muestras de cd/html dinámico/ instalación npm nodo.
Lo que inicia un servidor node.js para que las llamadas AJAX tengan un lugar al que ir.
Para hacerlo, simplemente use el indicador -l html cuando lea un archivo de especificaciones. Esto crea un archivo HTML único y simple con CSS incorporado para que pueda enviarlo como un archivo adjunto de correo electrónico o cargarlo desde su sistema de archivos:
muestras de cd/html/ abrir index.html
Es posible aprovechar Swagger Codegen directamente dentro de sus flujos de trabajo de CI/CD preferidos para optimizar sus requisitos de generación automática. Consulte la guía de integración de flujos de trabajo para ver información sobre nuestras opciones de integración de Maven, Gradle y GitHub. ?
Si no desea ejecutar y alojar su propia instancia de generación de código, consulte nuestra información sobre generadores en línea.
Por favor consulte esta página
Los miembros del equipo central de Swagger Codegen son contribuyentes que han realizado contribuciones significativas (revisar problemas, corregir errores, realizar mejoras, etc.) al proyecto de forma regular.
Los miembros del equipo central asumen las siguientes responsabilidades:
Proporciona orientación y dirección a otros usuarios.
Revisa solicitudes de extracción y problemas
Mejora el generador realizando mejoras, corrigiendo errores o actualizando documentaciones.
Establece la dirección técnica del generador.
Informe cualquier problema o vulnerabilidad relacionada con la seguridad enviando un correo electrónico a [email protected], en lugar de utilizar el rastreador de problemas público.
El proyecto Swagger Codegen pretende ser un beneficio para los usuarios de la especificación Swagger/Open API. El proyecto en sí tiene la Licencia especificada. Además, comprenda los siguientes puntos:
Las plantillas incluidas en este proyecto están sujetas a la Licencia.
El código generado intencionalmente no está sujeto a la licencia del proyecto principal.
Cuando se genere código a partir de este proyecto, se considerará TAL CUAL y será propiedad del usuario del software. No existen garantías, expresas o implícitas, para el código generado. Puede hacer lo que desee con él y, una vez generado, el código es su responsabilidad y está sujeto a los términos de licencia que considere apropiados.
Nos gustaría agradecer a todos aquellos que han contribuido a Swagger Codegen, ya sea planteando problemas, corrigiendo errores, creando plantillas o creando contenido útil para que otros se beneficien.
