swagger-codegen

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

swagger-codegen

★ 17,778 Open GitHub ↗

swagger-codegen은 OpenAPI / Swagger 정의를 파싱하여 다양한 언어로 문서, API 클라이언트 및 서버 스텁을 생성하는 템플릿 기반 엔진을 포함하고 있습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Swagger Codegen
![Swagger Codegen Logo](https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/docs/Swagger-Codegen-Logo.png)
이것은 [OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification)이 주어지면 API 클라이언트 라이브러리(SDK 생성), 서버 스텁, 문서를 자동으로 생성할 수 있게 해주는 Swagger Codegen 프로젝트입니다.
💚 기여하고 싶으시다면 [가이드라인](https://github.com/swagger-api/swagger-codegen/blob/master/CONTRIBUTING.md)과 [오픈 태스크 목록](https://github.com/swagger-api/swagger-codegen/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)을참조해 주세요.💚
📔 자세한 정보는 [Wiki 페이지](https://github.com/swagger-api/swagger-codegen/wiki)와 [FAQ](https://github.com/swagger-api/swagger-codegen/wiki/FAQ)를 참조해 주세요. 📔
⚠️ OpenAPI Description 또는 Swagger 파일을 신뢰할 수 없는 출처에서 가져온 경우, [코드 인젝션](https://en.wikipedia.org/wiki/Code\_injection)이 발생할 수 있으므로 Swagger Codegen을 사용하여 API 클라이언트, 서버 스텁 또는 문서를 생성하기 전에 반드시 아티팩트를 검토하시기 바랍니다. ⚠️
## Versioning
> ⚠️ 이 문서는 2.X 버전을 다루고 있으며, 3.X 버전은 [여기](https://github.com/swagger-api/swagger-codegen/tree/3.0.0)를 확인하세요.
Swagger Codegen의 \*\*2.X\*\* 및 \*\*3.X\*\* 버전 라인은 모두 사용할 수 있으며 독립적으로 유지 관리됩니다.
\*\*참고:\*\*
- 버전 2.X (`io.swagger`)와 3.X (`io.swagger.codegen.v3`)는 \*\*서로 다른\*\* 그룹 ID를 가집니다.
- OpenAPI 3.0.X는 3.X 버전에서만 지원됩니다.
전체 버전 정보는 [버전 관리 문서](./docs/versioning.md)를 참조하세요.
## Supported Languages and Frameworks
현재 다음과 같은 언어/프레임워크가 지원됩니다:
- \*\*API clients\*\*: \*\*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 Client Library for Java, Rest-assured), \*\*Kotlin\*\*, \*\*Lua\*\*, \*\*Node.js\*\* (ES5, ES6, AngularJS with Google Closure Compiler annotations) \*\*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)
- \*\*Server stubs\*\*: \*\*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](https://github.com/ProKarma-Inc/pkmst-getting-started-examples)), \*\*Kotlin\*\*, \*\*PHP\*\* (Lumen, Slim, Silex, [Symfony](https://symfony.com/), [Zend Expressive](https://github.com/zendframework/zend-expressive)), \*\*Python\*\* (Flask), \*\*NodeJS\*\*, \*\*Ruby\*\* (Sinatra, Rails5), \*\*Rust\*\* (rust-server), \*\*Scala\*\* ([Finch](https://github.com/finagle/finch), [Lagom](https://github.com/lagom/lagom), Scalatra)
- \*\*API documentation generators\*\*: \*\*HTML\*\*, \*\*Confluence Wiki\*\*
- \*\*Configuration files\*\*: [\*\*Apache2\*\*](https://httpd.apache.org/)
- \*\*Others\*\*: \*\*JMeter\*\*
OpenAPI 프로젝트에 대한 추가 정보는 [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification)을 확인하세요.
## Table of contents
- [Versioning](#versioning)
- [Compatibility](#compatibility)
- [Getting Started](#getting-started)
- [Generators](#generators)
- [To generate a sample client library](#to-generate-a-sample-client-library)
- [Generating libraries from your server](#generating-libraries-from-your-server)
- [Validating your OpenAPI Spec](#validating-your-openapi-spec)
- [Genera

ting dynamic html api documentation](#generating-dynamic-html-api-documentation)
- [동적 HTML API 문서 생성하기](#generating-dynamic-html-api-documentation)
- [워크플로우 통합](#workflow-integration)
- [온라인 생성기](#online-generators)
- [기여하기](#contributing)
- [Swagger Codegen 코어 팀](#swagger-codegen-core-team)
## 호환성
OpenAPI Specification은 2010년 최초 생성 이후 3차례의 개정을 거쳤습니다. Swagger Codegen 프로젝트의 \*\*현재 안정(stable)\*\* 버전은 OpenAPI Specification과 다음과 같은 호환성을 가집니다:
Swagger Codegen 버전 | 릴리스 날짜 | Swagger / OpenAPI Spec 호환성 | 참고 사항
-------------------------- |--------------| -------------------------- | -----
[3.0.71](https://github.com/swagger-api/swagger-codegen/releases/tag/v3.0.71) (\*\*현재 안정 버전\*\*) | 2025-07-03 | 1.0, 1.1, 1.2, 2.0, 3.0 | [태그 v3.0.71](https://github.com/swagger-api/swagger-codegen/tree/v3.0.71)
[2.4.46](https://github.com/swagger-api/swagger-codegen/releases/tag/v2.4.46) (\*\*현재 안정 버전\*\*) | 2025-06-30 | 1.0, 1.1, 1.2, 2.0 | [태그 v2.4.46](https://github.com/swagger-api/swagger-codegen/tree/v2.4.46)
💁 향후 출시될 예정인 기능에 대한 개요는 다음과 같습니다:
Swagger Codegen 버전 | 릴리스 날짜 | Swagger / OpenAPI Spec 호환성 | 참고 사항
-------------------------- |--------------| -------------------------- | -----
3.0.72-SNAPSHOT (현재 3.0.0, 다마 릴리스 예정) [SNAPSHOT](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/io/swagger/codegen/v3/swagger-codegen-cli/3.0.72-SNAPSHOT/)| 미정 | 1.0, 1.1, 1.2, 2.0, 3.0 | 마이너 릴리스
2.4.47-SNAPSHOT (현재 master, 마이너 릴리스 예정) [SNAPSHOT](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/io/swagger/swagger-codegen-cli/2.4.47-SNAPSHOT/)| 미정 | 1.0, 1.1, 1.2, 2.0 | 마이너 릴리스
모든 버전에 대한 자세한 내역은 [전체 호환성 목록](./docs/compatibility.md)을 참고해 주세요.
### 시작하기
Swagger Codegen을 시작하고 실행하려면 다음 가이드와 지침을 확인하세요:
- [사전 요구 사항](./docs/prerequisites.md)
- [빌드하기](./docs/building.md)
- [Docker 사용하기](./docs/docker.md)
환경 설정이 완료되면 클라이언트 및/또는 서버 생성을 시작할 준비가 된 것입니다.
간단한 예시로, https://petstore.swagger.io/v2/swagger.json을 위한 PHP 클라이언트를 생성하려면 다음 명령을 실행할 수 있습니다:
```sh
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l php \
-o /var/tmp/php\_api\_client
```
\*\*참고:\*\* Windows를 사용하는 경우, 마지막 명령을 다음과 같이 변경하세요:
```sh
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i https://petstore.swagger.io/v2/swagger.json -l php -o c:\temp\php\_api\_client
```
또한 [maven.org](https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.46/swagger-codegen-cli-2.4.46.jar)에서 JAR(최신 릴리스)을 직접 다운로드할 수 있습니다.
사용 가능한 \*\*일반\*\* 옵션 목록을 보려면 다음을 실행하세요:
```sh
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar help generate
```
PHP 지정 옵션 목록을 보려면(`-c` 옵션을 통해 설정 파일과 함께 생성기에 전달할 수 있음), 다음을 실행하세요:
```sh
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
```
## 생성기(Generators)
### 샘플 클라이언트 라이브러리 생성하기
Swagger 샘플 [petstore](https://petstore.swagger.io) API를 기반으로 클라이언트를 빌드할 수 있습니다:
```sh
./bin/java-petstore.sh
```
(Windows의 경우, 대신 `.\bin\windows\java-petstore.bat`를 실행하세요)
이 명령은 다음 명령어로 생성기를 실행합니다:
```sh
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l java \
-o samples/client/petstore/java
```
w

다양한 옵션이 제공됩니다. `help generate` 명령어를 통해 옵션을 확인할 수 있습니다 (아래 결과는 일부만 표시된 것입니다):
```text
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
```
그런 다음 클라이언트와 이에 대한 단위 테스트를 컴파일하고 실행할 수 있습니다:
```sh
cd samples/client/petstore/java
mvn package
```
다른 언어로 된 petstore 샘플도 존재합니다:
```sh
./bin/android-petstore.sh
./bin/java-petstore.sh
./bin/objc-petstore.sh
```
### 서버에서 라이브러리 생성하기
매우 간단합니다. `-i` 플래그를 사용하여 서버나 파일을 지정하기만 하면 됩니다.
🔧 Swagger Codegen은 코드 생성 기본 설정을 지원하기 위해 엄청난 유연성을 제공합니다. [generators documentation](./docs/generators.md)을 확인하여 다양한 가능성을 살펴보고 로컬 파일에서 생성하는 방법과 파일 형식 무시 방법을 확인해 보세요.
### 선택적 생성
프로젝트의 \*모든\* 모델을 생성하고 싶지 않을 수도 있습니다. 마찬가지로 하나 또는 두 개의 API만 작성하고 싶을 수도 있습니다. 그렇다면 [selective generation](./docs/generation-selective.md) 안내서를 확인하세요.
### 고급 제너레이터 커스터마이징
템플릿을 생성하거나 수정하는 것 외에도 코드 제너레이터를 커스터마이징하는 다양한 측면이 있습니다. 각 언어에는 다양한 타입 매핑을 처리하거나 자체 모델을 가져올 수 있도록 지원하는 설정 파일이 있습니다. 자세한 내용은 [advanced configuration docs](./docs/generators-configuration.md)를 확인하세요.
### OpenAPI Spec 검증하기
다양한 방법이 있습니다. 가장 쉬운 방법은 [online validator](https://github.com/swagger-api/validator-badge)를 사용하는 것입니다. 이를 통해 스펙을 검증할 수 있을 뿐만 아니라 디버그 플래그를 사용하여 스펙의 문제점을 확인할 수도 있습니다. 예를 들어 [Swagger Validator](http://online.swagger.io/validator/debug?url=https://petstore.swagger.io/v2/swagger.json)를 확인해 보세요.
내 컴퓨터에서 직접 검증을 수행하고 싶다면 [Spectral](https://stoplight.io/open-source/spectral)이 훌륭한 선택입니다.
### 동적 HTML API 문서 생성하기
스펙 파일을 읽을 때 `-l dynamic-html` 플래그를 사용하기만 하면 됩니다. 이렇게 하면 AJAX를 사용하는 싱글 페이지 애플리케이션 형태의 HTML 문서가 생성됩니다. 문서를 보려면 다음을 실행하세요:
```sh
cd samples/dynamic-html/
npm install
node .
```
위 명령어는 AJAX 호출이 정상적으로 동작할 수 있도록 node.js 서버를 실행합니다.
### 정적 HTML API 문서 생성하기
스펙 파일을 읽을 때 `-l html` 플래그를 사용하기만 하면 됩니다. 이렇게 하면 CSS가 포함된 단일의 간단한 HTML 파일이 생성되므로 이메일 첨부 파일로 보내거나 파일 시스템에서 바로 로드할 수 있습니다:
```sh
cd samples/html/
open index.html
```
## 워크플로우 통합
선호하는 CI/CD 워크플로우 내에서 Swagger Codegen을 직접 활용하여 자동 생성 요구사항을 간소화할 수 있습니다. [workflows integration](./docs/workflow-integration.md) 가이드를 확인하여 Maven, Gradle 및 GitHub 통합 옵션에 대한 정보를 확인하세요. 🚀
## 온라인 제너레이터
직접 코드 생성 인스턴스를 실행하고 호스팅하고 싶지 않다면, [online generators](./do

cs/online-generators.md) 정보를 참고하세요.
## 기여하기
[이 페이지](https://github.com/swagger-api/swagger-codegen/blob/master/CONTRIBUTING.md)를 참고해 주세요.
## Swagger Codegen 핵심 팀
Swagger Codegen 핵심 팀 멤버는 프로젝트에 지속적으로 중요한 기여(이슈 검토, 버그 수정, 기능 개선 등)를 해온 기여자들입니다.
핵심 팀 멤버는 다음과 같은 책임을 맡습니다:
- 다른 사용자에게 가이드라인과 방향성 제시
- 풀 리퀘스트 및 이슈 검토
- 기능 개선, 버그 수정 또는 문서 업데이트를 통한 generator 개선
- generator의 기술적 방향성 설정
## 보안 연락처
보안과 관련된 이슈나 취약점을 공개 이슈 트래커에 올리는 대신, [security@swagger.io](mailto:security@swagger.io)로 이메일을 보내어 제보해 주세요.
## 생성된 코드의 라이선스 정보
Swagger Codegen 프로젝트는 Swagger / Open API Specification 사용자의 이익을 위해 제공됩니다. 프로젝트 자체는 명시된 [라이선스](./LICENSE)를 따릅니다. 추가로 다음 사항을 양해해 주시기 바랍니다:
- 이 프로젝트에 포함된 템플릿은 [라이선스](./LICENSE)의 적용을 받습니다.
- 생성된 코드는 상위 프로젝트 라이선스의 적용을 의도적으로 받지 \_않습니다\_
이 프로젝트에서 코드가 생성되면 해당 코드는 \*\*있는 그대로(AS IS)\*\* 간주되며 소프트웨어 사용자에게 소유권이 있습니다. 생성된 코드에 대해서는 명시적이든 묵시적이든 어떠한 보증도 제공되지 않습니다. 사용자는 원하는 대로 코드를 사용할 수 있으며, 일단 생성된 코드는 사용자의 책임하에 적절하다고 판단되는 라이선스 조건에 따르게 됩니다.
## 감사의 말
💚💚💚 이슈 제기, 버그 수정, [템플릿 작성](./docs/template-creators.md), 또는 다른 이들에게 도움이 되는 유용한 [콘텐츠 제작](./docs/public-content.md) 등 Swagger Codegen에 기여해주신 모든 분들께 진심으로 감사의 말씀을 전합니다. 💚💚💚

swagger-codegen

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README