스웨거 코드젠

기타 소스코드

Swagger

다운로드

스웨거 코드젠

이것은 OpenAPI 사양에 따라 API 클라이언트 라이브러리(SDK 생성), 서버 스텁 및 문서를 자동으로 생성할 수 있는 Swagger Codegen 프로젝트입니다.

기여하고 싶다면 지침과 진행 중인 작업 목록을 참조하세요.

자세한 내용은 Wiki 페이지 및 FAQ를 참조하세요.

⚠️ OpenAPI 설명 또는 Swagger 파일을 신뢰할 수 없는 소스에서 얻은 경우 코드 삽입이 발생할 수 있으므로 Swagger Codegen을 사용하여 API 클라이언트, 서버 스텁 또는 문서를 생성하기 전에 아티팩트를 검토했는지 확인하십시오. ⚠️

버전 관리

⚠️ 이 문서는 버전 2.X를 나타냅니다. 3.X는 여기를 확인하세요.

Swagger Codegen의 2.X 및 3.X 버전 라인을 모두 사용할 수 있으며 독립적으로 유지 관리됩니다.

참고:

버전 2.X( io.swagger )와 3.X( io.swagger.codegen.v3 )는 그룹 ID가 다릅니다 .
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 , 에펠 , Erlang , Go , Groovy , Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Java용 Google API 클라이언트 라이브러리, 안심), Kotlin , Lua , Node.js (Google Closure Compiler 주석이 포함된 ES5, ES6, AngularJS) 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-server), Scala (Finch, Lagom, 스칼라트라)
API 문서 생성기 : HTML , Confluence Wiki
구성 파일 : Apache2
기타 : JMeter

OpenAPI 프로젝트에 대한 추가 정보는 OpenAPI-Spec을 확인하세요.

호환성

OpenAPI 사양은 2010년 처음 생성된 이후 3번의 개정을 거쳤습니다. Swagger Codegen 프로젝트의 현재 안정 버전은 OpenAPI 사양과 다음과 같은 호환성을 갖습니다.

Swagger Codegen 버전	출시일	Swagger/OpenAPI 사양 호환성	메모
3.0.62 ( 현재 안정 )	2024-08-27	1.0, 1.1, 1.2, 2.0, 3.0	태그 v3.0.62
2.4.43 ( 현재 안정 )	2024-08-09	1.0, 1.1, 1.2, 2.0	태그 v2.4.42

또한 앞으로 다가올 내용에 대한 개요는 다음과 같습니다.

Swagger Codegen 버전	출시일	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을 시작하고 실행하려면 다음 가이드와 지침을 확인하세요.

전제 조건
건물
도커 사용

환경 설정이 완료되면 클라이언트 및/또는 서버 생성을 시작할 준비가 된 것입니다.

간단한 예로 https://petstore.swagger.io/v2/swagger.json에 대한 PHP 클라이언트를 생성하려면 다음을 실행할 수 있습니다.

 자식 클론 https://github.com/swagger-api/swagger-codegencd swagger-codegen
mvn 클린 패키지
자바 -jar 모듈/swagger-codegen-cli/target/swagger-codegen-cli.jar 생성
    -i https://petstore.swagger.io/v2/swagger.json
    -l 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

maven.org에서 직접 JAR(최신 릴리스)을 다운로드할 수도 있습니다.

사용 가능한 일반 옵션 목록을 얻으려면 다음을 실행하세요.

 java -jar 모듈/swagger-codegen-cli/target/swagger-codegen-cli.jar 도움말 생성

PHP 지정 옵션 목록을 얻으려면( -c 옵션을 통해 구성 파일과 함께 생성기에 전달할 수 있음) 다음을 실행하십시오.

 자바 -jar 모듈/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php

발전기

샘플 클라이언트 라이브러리를 생성하려면

다음과 같이 swagger 샘플 petstore API에 대해 클라이언트를 구축할 수 있습니다.

 ./bin/java-petstore.sh

(Windows에서는 대신 .binwindowsjava-petstore.bat 실행하세요.)

그러면 다음 명령으로 생성기가 실행됩니다.

 자바 -jar 모듈/swagger-codegen-cli/target/swagger-codegen-cli.jar 생성
   -i https://petstore.swagger.io/v2/swagger.json
   -l 자바
   -o 샘플/클라이언트/petstore/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

그런 다음 클라이언트를 컴파일하고 실행할 수 있을 뿐만 아니라 클라이언트에 대한 단위 테스트도 수행할 수 있습니다.

 CD 샘플/클라이언트/petstore/java
mvn 패키지

다른 언어에도 petstore 샘플이 있습니다.

 ./bin/android-petstore.sh
./bin/java-petstore.sh
./bin/objc-petstore.sh

서버에서 라이브러리 생성

마찬가지로 쉽습니다. -i 플래그를 사용하여 서버나 파일을 가리키기만 하면 됩니다.

? Swagger Codegen은 코드 생성 기본 설정을 지원하는 엄청난 유연성을 제공합니다. 몇 가지 가능성을 안내하고 로컬 파일에서 생성하고 파일 형식을 무시하는 방법을 보여주는 생성기 문서를 확인하세요.

선택적 생성

프로젝트에서 모든 모델을 생성하고 싶지 않을 수도 있습니다. 마찬가지로 하나 또는 두 개의 API만 작성하기를 원할 수도 있습니다. 그렇다면 선택적 생성 지침을 확인하세요.

고급 생성기 사용자 정의

단순히 템플릿을 생성하거나 수정하는 것 외에 코드 생성기를 사용자 정의하는 데에는 다양한 측면이 있습니다. 각 언어에는 다양한 유형 매핑을 처리하거나 고유한 모델을 가져오기 위한 지원 구성 파일이 있습니다. 자세한 내용은 고급 구성 문서를 확인하세요.

OpenAPI 사양 검증

당신에게는 선택권이 있습니다. 가장 쉬운 방법은 사양을 검증할 수 있을 뿐만 아니라 디버그 플래그를 사용하여 사양에 어떤 문제가 있는지 확인할 수 있는 온라인 유효성 검사기를 사용하는 것입니다. 예를 들어 Swagger Validator를 확인하세요.

자신의 컴퓨터에서 직접 검증을 원할 경우 Spectral이 탁월한 선택입니다.

동적 HTML API 문서 생성

그렇게 하려면 사양 파일을 읽을 때 -l dynamic-html 플래그를 사용하면 됩니다. 그러면 AJAX를 사용하여 단일 페이지 애플리케이션으로 사용할 수 있는 HTML 문서가 생성됩니다. 설명서를 보려면:

 CD 샘플/동적-html/
npm 설치
노드 .

AJAX 호출을 수행할 수 있도록 node.js 서버를 시작합니다.

정적 HTML API 문서 생성

그렇게 하려면 사양 파일을 읽을 때 -l html 플래그를 사용하면 됩니다. 그러면 CSS가 포함된 간단한 단일 HTML 파일이 생성되므로 이메일 첨부 파일로 제공하거나 파일 시스템에서 로드할 수 있습니다.

 CD 샘플/html/
index.html 열기

워크플로우 통합

선호하는 CI/CD 워크플로 내에서 Swagger Codegen을 직접 활용하여 자동 생성 요구 사항을 간소화할 수 있습니다. Maven, Gradle 및 GitHub 통합 옵션에 대한 정보를 보려면 워크플로 통합 가이드를 확인하세요. ?

온라인 생성기

자체 코드 생성 인스턴스를 실행하고 호스팅하고 싶지 않은 경우 온라인 생성기 정보를 확인하세요.

기여

이 페이지를 참고하세요

Swagger Codegen 핵심 팀

Swagger Codegen 핵심 팀 구성원은 정기적으로 프로젝트에 상당한 기여(문제 검토, 버그 수정, 개선 등)를 해 온 기여자입니다.

핵심 팀의 구성원은 다음과 같은 책임을 맡습니다.

다른 사용자에게 지침과 방향을 제공합니다.
풀 요청 및 문제 검토
개선, 버그 수정 또는 문서 업데이트를 통해 생성기를 개선합니다.
발전기의 기술적 방향을 설정합니다.

보안 연락처

공개 문제 추적기를 사용하는 대신 [email protected]로 이메일을 보내 보안 관련 문제나 취약점을 공개해 주십시오.

생성된 코드에 대한 라이센스 정보

Swagger Codegen 프로젝트는 Swagger/Open API 사양 사용자를 위한 혜택으로 만들어졌습니다. 프로젝트 자체에는 지정된 라이선스가 있습니다. 또한, 다음 사항을 이해하시기 바랍니다.

이 프로젝트에 포함된 템플릿에는 라이선스가 적용됩니다.
생성된 코드에는 의도적으로 상위 프로젝트 라이선스가 적용되지 않습니다 .

이 프로젝트에서 코드가 생성되면 해당 코드는 있는 그대로 간주되며 소프트웨어 사용자가 소유하게 됩니다. 생성된 코드에 대해서는 명시적이든 묵시적이든 어떠한 보증도 없습니다. 원하는 대로 무엇이든 할 수 있으며, 일단 생성된 코드는 귀하의 책임이며 귀하가 적절하다고 생각하는 라이선스 조건의 적용을 받습니다.