código de arrogância
Swagger
Este é o projeto Swagger Codegen, que permite a geração de bibliotecas de clientes API (geração de SDK), stubs de servidor e documentação automaticamente com uma especificação OpenAPI.
Se você gostaria de contribuir, consulte as diretrizes e uma lista de tarefas abertas.
Para obter mais informações, consulte a página Wiki e FAQ?
⚠️ este documento refere-se à versão 2.X, verifique aqui a versão 3.X.
Ambas as linhas de versões 2.X e 3.X do Swagger Codegen estão disponíveis e são mantidas de forma independente.
NOTAS:
As versões 2.X ( io.swagger ) e 3.X ( io.swagger.codegen.v3 ) possuem IDs de grupo diferentes .
OpenAPI 3.0.X é compatível apenas com a versão 3.X.
Para obter informações completas sobre controle de versão, consulte a documentação de controle de versão.
Atualmente, as seguintes linguagens/estruturas são suportadas:
Clientes API : ActionScript , Ada , Apex , Bash , C# (.net 2.0, 3.5 ou posterior), C++ (cpprest, Qt5, Tizen), Clojure , Dart , Elixir , Elm , Eiffel , Erlang , Go , Groovy , Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Biblioteca cliente API do Google para Java, tenha certeza), Kotlin , Lua , Node.js (ES5, ES6, AngularJS com anotações do Google Closure Compiler) Objective-C , Perl , PHP , PowerShell , Python , R , Ruby , Rust (rust, ferrugem-server), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Stubs 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 (rust-server), Scala (Finch, Lagom, Scalatra)
Geradores de documentação de API : HTML , Confluence Wiki
Arquivos de configuração : Apache2
Outros : JMeter
Confira OpenAPI-Spec para obter informações adicionais sobre o projeto OpenAPI.
Versionamento
Compatibilidade
Começando
Geradores
Para gerar uma biblioteca cliente de amostra
Gerando bibliotecas do seu servidor
Validando sua especificação OpenAPI
Gerando documentação de API HTML dinâmica
Gerando documentação estática da API HTML
Integração de fluxo de trabalho
Geradores on-line
Contribuição
Equipe principal do Swagger Codegen
A especificação OpenAPI passou por 3 revisões desde a criação inicial em 2010. As versões estáveis atuais do projeto Swagger Codegen têm as seguintes compatibilidades com a especificação OpenAPI:
| Versão Swagger Codegen | Data de lançamento | Compatibilidade com especificações Swagger/OpenAPI | Notas |
|---|---|---|---|
| 3.0.62 ( atualmente estável ) | 27/08/2024 | 1,0, 1,1, 1,2, 2,0, 3,0 | etiqueta v3.0.62 |
| 2.4.43 ( atualmente estável ) | 09/08/2024 | 1,0, 1,1, 1,2, 2,0 | etiqueta v2.4.42 |
Aqui está também uma visão geral do que está por vir:
| Versão Swagger Codegen | Data de lançamento | Compatibilidade com especificações Swagger/OpenAPI | Notas |
|---|---|---|---|
| 3.0.63-SNAPSHOT (atual 3.0.0, próximo lançamento secundário) SNAPSHOT | A definir | 1,0, 1,1, 1,2, 2,0, 3,0 | Lançamento secundário |
| 2.4.44-SNAPSHOT (master atual, próximo lançamento secundário) INSTANTÂNEO | A definir | 1,0, 1,1, 1,2, 2,0 | Lançamento secundário |
Para uma análise detalhada de todas as versões, consulte a lista completa de compatibilidade.
Para começar a usar o Swagger Codegen, verifique os seguintes guias e instruções:
Pré-requisitos
Prédio
Usando Docker
Depois de configurar seu ambiente, você estará pronto para começar a gerar clientes e/ou servidores.
Como um exemplo rápido, para gerar um cliente PHP para https://petstore.swagger.io/v2/swagger.json, você pode executar o seguinte:
clone do git https://github.com/swagger-api/swagger-codegencd swagger-codegen
pacote limpo mvn
java -jar módulos/swagger-codegen-cli/target/swagger-codegen-cli.jar gerar
-i https://petstore.swagger.io/v2/swagger.json
-lphp
-o /var/tmp/php_api_clientNota: se você estiver no Windows, substitua o último comando por
java -jar módulosswagger-codegen-clitargetswagger-codegen-cli.jar gerar -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
Você também pode baixar o JAR (versão mais recente) diretamente em maven.org
Para obter uma lista de opções gerais disponíveis, você pode executar o seguinte:
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar ajuda a gerar
Para obter uma lista de opções especificadas pelo PHP (que podem ser passadas para o gerador com um arquivo de configuração através da opção -c ), execute
java -jar módulos/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
Você pode criar um cliente com base na API petstore de amostra swagger da seguinte maneira:
./bin/java-petstore.sh
(No Windows, execute .binwindowsjava-petstore.bat )
Isso executará o gerador com este comando:
java -jar módulos/swagger-codegen-cli/target/swagger-codegen-cli.jar gerar -i https://petstore.swagger.io/v2/swagger.json -eu java -o amostras/cliente/petstore/java
com uma série de opções. Você pode obter as opções com o comando help generate (abaixo mostra apenas resultados parciais):
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 Você pode então compilar e executar o cliente, bem como fazer testes de unidade nele:
amostras de cd/cliente/petstore/java pacote mvn
Outros idiomas também têm amostras de petstore:
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
É igualmente fácil: basta usar o sinalizador -i para apontar para um servidor ou arquivo.
? Swagger Codegen vem com muita flexibilidade para oferecer suporte às suas preferências de geração de código. Confira a documentação dos geradores que mostra algumas das possibilidades, além de mostrar como gerar a partir de arquivos locais e ignorar formatos de arquivo.
Talvez você não queira gerar todos os modelos em seu projeto. Da mesma forma, você pode querer que apenas uma ou duas APIs sejam escritas. Se for esse o caso, verifique as instruções de geração seletiva.
Existem diferentes aspectos de personalização do gerador de código além de apenas criar ou modificar modelos. Cada linguagem possui um arquivo de configuração de suporte para lidar com mapeamentos de diferentes tipos ou trazer seus próprios modelos. Para obter mais informações, consulte os documentos de configuração avançada.
Você tem opções. O mais fácil é usar nosso validador online, que não apenas permitirá validar suas especificações, mas com o sinalizador de depuração, você poderá ver o que há de errado com suas especificações. Por exemplo, verifique o Swagger Validator.
Se você deseja ter a validação diretamente em sua máquina, então Spectral é uma excelente opção.
Para fazer isso, basta usar o sinalizador -l dynamic-html ao ler um arquivo de especificações. Isso cria documentação HTML que está disponível como um aplicativo de página única com AJAX. Para visualizar a documentação:
amostras de cd/html dinâmico/ instalação npm nó.
O que inicia um servidor node.js para que as chamadas AJAX tenham um lugar para ir.
Para fazer isso, basta usar o sinalizador -l html ao ler um arquivo de especificações. Isso cria um arquivo HTML único e simples com CSS incorporado para que você possa enviá-lo como anexo de e-mail ou carregá-lo do seu sistema de arquivos:
amostras de cd/html/ abra index.html
É possível aproveitar o Swagger Codegen diretamente em seus fluxos de trabalho de CI/CD preferidos para agilizar seus requisitos de geração automática. Confira o guia de integração de fluxos de trabalho para ver informações sobre nossas opções de integração Maven, Gradle e GitHub. ?
Se você não deseja executar e hospedar sua própria instância de geração de código, verifique nossas informações sobre geradores online.
Por favor consulte esta página
Os membros da equipe principal do Swagger Codegen são contribuidores que têm feito contribuições significativas (revisar problemas, corrigir bugs, fazer melhorias, etc.) para o projeto regularmente.
Os membros da equipe principal assumem as seguintes responsabilidades:
Fornece orientação e direção para outros usuários
Revisa solicitações pull e problemas
Melhora o gerador fazendo melhorias, corrigindo bugs ou atualizando documentações
Define a direção técnica do gerador
Divulgue quaisquer problemas ou vulnerabilidades relacionadas à segurança enviando um e-mail para [email protected], em vez de usar o rastreador de problemas público.
O projeto Swagger Codegen pretende ser um benefício para usuários da especificação Swagger/Open API. O projeto em si possui a Licença conforme especificado. Além disso, entenda os seguintes pontos:
Os modelos incluídos neste projeto estão sujeitos à Licença.
O código gerado não está intencionalmente sujeito à licença do projeto pai
Quando o código for gerado a partir deste projeto, ele será considerado COMO ESTÁ e de propriedade do usuário do software. Não há garantias – expressas ou implícitas – para o código gerado. Você pode fazer o que quiser com ele e, uma vez gerado, o código é de sua responsabilidade e sujeito aos termos de licenciamento que você considerar apropriados.
Gostaríamos de agradecer a todos aqueles que contribuíram para o Swagger Codegen, seja levantando problemas, corrigindo bugs, criando modelos ou criando conteúdo útil para outros se beneficiarem.
