чванство кодоген
Swagger
Это проект Swagger Codegen, который позволяет автоматически создавать клиентские библиотеки API (создание SDK), серверные заглушки и документацию с учетом спецификации OpenAPI.
Если вы хотите внести свой вклад, ознакомьтесь с рекомендациями и списком открытых задач.
Для получения дополнительной информации, пожалуйста, обратитесь к странице Wiki и разделу часто задаваемых вопросов?
⚠️ этот документ относится к версии 2.X, проверьте здесь версию 3.X.
Обе версии Swagger Codegen 2.X и 3.X доступны и поддерживаются независимо.
ПРИМЕЧАНИЯ:
Версии 2.X ( io.swagger ) и 3.X ( io.swagger.codegen.v3 ) имеют разные идентификаторы групп.
OpenAPI 3.0.X поддерживается только начиная с версии 3.X.
Полную информацию о версиях см. в документации по версиям.
В настоящее время поддерживаются следующие языки/фреймворки:
Клиенты API : ActionScript , Ada , Apex , Bash , C# (.net 2.0, 3.5 или новее), 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, Клиентская библиотека Google API для Java, будьте уверены), Kotlin , Lua , Node.js (ES5, ES6, AngularJS с аннотациями компилятора Google Closure) Objective-C , Perl , PHP , PowerShell , Python , R , Ruby , Rust (rust,rust-server), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Серверные заглушки : 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-сервер), Scala (Finch, Lagom, Скалатра)
Генераторы документации API : HTML , Confluence Wiki
Конфигурационные файлы : Apache2.
Другие : JMeter
Посетите OpenAPI-Spec для получения дополнительной информации о проекте OpenAPI.
Управление версиями
Совместимость
Начиная
Генераторы
Создание примера клиентской библиотеки
Генерация библиотек с вашего сервера
Проверка вашей спецификации OpenAPI
Создание динамической документации html API
Создание статической документации html API
Интеграция рабочих процессов
Онлайн-генераторы
Вклад
Основная команда Swagger Codegen
Спецификация OpenAPI претерпела 3 изменения с момента первоначального создания в 2010 году. Текущие стабильные версии проекта Swagger Codegen имеют следующую совместимость со спецификацией OpenAPI:
| Версия кода Swagger | Дата выпуска | Совместимость со спецификациями Swagger/OpenAPI | Примечания |
|---|---|---|---|
| 3.0.62 ( текущая стабильная версия ) | 2024-08-27 | 1.0, 1.1, 1.2, 2.0, 3.0 | тег v3.0.62 |
| 2.4.43 ( текущая стабильная версия ) | 09.08.2024 | 1.0, 1.1, 1.2, 2.0 | тег v2.4.42 |
Вот также обзор того, что будет в ближайшем будущем:
| Версия кода Swagger | Дата выпуска | Совместимость со спецификациями Swagger/OpenAPI | Примечания |
|---|---|---|---|
| 3.0.63-SNAPSHOT (текущая версия 3.0.0, предстоящий дополнительный выпуск) SNAPSHOT | подлежит уточнению | 1.0, 1.1, 1.2, 2.0, 3.0 | Незначительный выпуск |
| 2.4.44-SNAPSHOT (текущий основной, предстоящий дополнительный выпуск) SNAPSHOT | подлежит уточнению | 1.0, 1.1, 1.2, 2.0 | Незначительный выпуск |
Подробную информацию обо всех версиях см. в полном списке совместимости.
Чтобы начать работу с Swagger Codegen, ознакомьтесь со следующими руководствами и инструкциями:
Предварительные условия
Здание
Использование Докера
После настройки среды вы готовы приступить к созданию клиентов и/или серверов.
В качестве быстрого примера: чтобы создать PHP-клиент для https://petstore.swagger.io/v2/swagger.json, вы можете запустить следующее:
git clone https://github.com/swagger-api/swagger-codegencd swagger-codegen
чистый пакет mvn
java -jar модули/swagger-codegen-cli/target/swagger-codegen-cli.jar генерировать
-i https://petstore.swagger.io/v2/swagger.json
-л php
-o /var/tmp/php_api_clientПримечание. Если вы используете Windows, замените последнюю команду на
java -jar модулиswagger-codegen-clitargetswagger-codegen-cli.jar генерировать -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
Вы также можете загрузить JAR (последнюю версию) непосредственно с maven.org.
Чтобы получить список доступных общих опций, вы можете запустить следующее:
java -jar модули/swagger-codegen-cli/target/swagger-codegen-cli.jar помогают генерировать
Чтобы получить список указанных параметров PHP (который можно передать генератору с помощью файла конфигурации через параметр -c ), запустите
java -jar модули/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
Вы можете создать клиент на основе API-интерфейса зоомагазина Swagger, выполнив следующие действия:
./bin/java-petstore.sh
(В Windows вместо этого запустите .binwindowsjava-petstore.bat )
Это запустит генератор с помощью этой команды:
java -jar модули/swagger-codegen-cli/target/swagger-codegen-cli.jar генерировать -i https://petstore.swagger.io/v2/swagger.json -л Ява -o образцы/клиент/зоомагазин/java
с рядом опций. Вы можете получить параметры с help generate (ниже показаны только частичные результаты):
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 Затем вы можете скомпилировать и запустить клиент, а также провести модульные тесты:
образцы компакт-дисков/клиент/зоомагазин/Java пакет mvn
На других языках тоже есть образцы из зоомагазинов:
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
Это так же просто: просто используйте флаг -i , чтобы указать сервер или файл.
? Swagger Codegen обладает огромной гибкостью для поддержки ваших предпочтений по генерации кода. Ознакомьтесь с документацией генераторов, которая познакомит вас с некоторыми возможностями, а также продемонстрирует, как генерировать генераторы из локальных файлов и игнорировать форматы файлов.
Возможно, вы не захотите создавать все модели в своем проекте. Аналогичным образом вы можете захотеть написать только один или два API. В этом случае проверьте инструкции по выборочной генерации.
Существуют различные аспекты настройки генератора кода, помимо простого создания или изменения шаблонов. Каждый язык имеет вспомогательный файл конфигурации для обработки различных сопоставлений типов или создания собственных моделей. Для получения дополнительной информации ознакомьтесь с документацией по расширенной конфигурации.
У вас есть варианты. Самый простой — использовать наш онлайн-валидатор, который не только позволит вам проверить вашу спецификацию, но и с помощью флага отладки вы сможете увидеть, что не так с вашей спецификацией. Например, проверьте Swagger Validator.
Если вы хотите провести проверку непосредственно на своем компьютере, Spectral — отличный вариант.
Для этого просто используйте флаг -l dynamic-html при чтении файла спецификации. При этом создается HTML-документация, доступная в виде одностраничного приложения с AJAX. Чтобы просмотреть документацию:
образцы компакт-дисков/динамический-html/ установка npm узел.
Который запускает сервер node.js, чтобы AJAX-вызовам было куда идти.
Для этого просто используйте флаг -l html при чтении файла спецификации. При этом создается один простой HTML-файл со встроенным CSS, который вы можете отправить в виде вложения к электронной почте или загрузить из своей файловой системы:
образцы компакт-дисков/html/ открыть index.html
Можно использовать Swagger Codegen непосредственно в предпочитаемых вами рабочих процессах CI/CD, чтобы упростить требования к автоматической генерации. Ознакомьтесь с руководством по интеграции рабочих процессов, чтобы увидеть информацию о наших вариантах интеграции Maven, Gradle и GitHub. ?
Если вы не хотите запускать и размещать собственный экземпляр генерации кода, ознакомьтесь с информацией о наших онлайн-генераторах.
Пожалуйста, обратитесь к этой странице
Члены основной команды Swagger Codegen — это участники, которые регулярно вносят значительный вклад (проверяют проблемы, исправляют ошибки, вносят улучшения и т. д.) в проект.
Члены основной команды выполняют следующие обязанности:
Предоставляет рекомендации и указания другим пользователям.
Обзоры запросов на включение и проблем
Улучшает генератор путем внесения улучшений, исправления ошибок или обновления документации.
Задает техническое направление генератора
Пожалуйста, сообщайте о любых проблемах или уязвимостях, связанных с безопасностью, по электронной почте [email protected] вместо использования общедоступного средства отслеживания проблем.
Проект Swagger Codegen предназначен для пользователей спецификации Swagger/Open API. Сам проект имеет указанную Лицензию. Кроме того, пожалуйста, поймите следующие моменты:
На шаблоны, включенные в этот проект, распространяется действие Лицензии.
Сгенерированный код намеренно не подпадает под действие лицензии родительского проекта.
Код, созданный на основе этого проекта, считается КАК ЕСТЬ и принадлежит пользователю программного обеспечения. На сгенерированный код не дается никаких гарантий — явных или подразумеваемых. Вы можете делать с ним все, что пожелаете, и после создания кода вы несете ответственность за него и подчиняетесь условиям лицензирования, которые вы считаете подходящими.
Мы хотели бы выразить огромную благодарность всем, кто внес свой вклад в Swagger Codegen, поднимая проблемы, исправляя ошибки, создавая шаблоны или создавая полезный контент для других.
