К основному содержанию
скилл CX Codex официальный · GitHub

openapi-to-application-java-spring-boot — скилл для GitHub Copilot

Скилл openapi-to-application-java-spring-boot для GitHub Copilot превращает спецификацию OpenAPI в основу приложения на Spring Boot. Он включается, когда нужно создать или доработать Java API по файлу OpenAPI или Swagger.

MIT ★ 41 430 обновлён 2026-10-23

Установить в GitHub Copilot · GitHub CLI Все способы и платформы ↓
gh skill install github/awesome-copilot skills/openapi-to-application-java-spring-boot
Открыть на GitHub

Что делает openapi-to-application-java-spring-boot

Скилл помогает собрать Spring Boot-приложение по спецификации OpenAPI в подходе spec-first: файл остаётся источником истины, а openapi-generator создаёт интерфейсы API и DTO. Реализацию контроллеров, сервисов, хранения данных, безопасности и тестов нужно написать отдельно. Генерируемый код не следует коммитить.

Скилл проверяет operationId, теги, схемы, ограничения валидации, ответы с ошибками и схемы безопасности, а затем настраивает генератор для Maven или Gradle. Он принимает OpenAPI 3.0.x и 3.1.x; Swagger 2.0 сначала нужно преобразовать. Для описанного процесса требуется JDK 21+; для Spring Boot 3.0/3.1 настройка валидации отличается от вариантов для 3.2+ и Boot 4.

Какие задачи решает

  • создать каркас Spring Boot API по спецификации OpenAPI
  • сгенерировать интерфейсы API и DTO через Maven или Gradle
  • найти пробелы в схемах, валидации и ответах с ошибками
  • настроить реализацию контроллеров и сервисов поверх API-интерфейсов

Примеры запросов агенту

  • Создай Spring Boot API по спецификации src/main/resources/openapi/store.yaml.
  • Настрой openapi-generator для этого OpenAPI-файла в проекте на Gradle.
  • Проверь спецификацию API и подготовь интерфейсы и DTO для Spring Boot.

Как установить openapi-to-application-java-spring-boot

1GitHub CLI

gh skill install github/awesome-copilot skills/openapi-to-application-java-spring-boot

2Вручную: положить файлы

.github/skills/openapi-to-application-java-spring-boot/SKILL.md

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об openapi-to-application-java-spring-boot

Как установить openapi-to-application-java-spring-boot в GitHub Copilot?

Выполни gh skill install github/awesome-copilot skills/openapi-to-application-java-spring-boot. Файл скилла появится по пути .github/skills/openapi-to-application-java-spring-boot/SKILL.md.

Что делает openapi-to-application-java-spring-boot?

Он настраивает создание интерфейсов API и DTO из OpenAPI-спецификации для Spring Boot. Контроллеры, сервисы, хранение данных, безопасность и тесты остаются ручной реализацией.

Что нужно для работы openapi-to-application-java-spring-boot?

Нужны спецификация OpenAPI 3.0.x или 3.1.x, JDK 21+ и openapi-generator; проект может использовать Maven или Gradle. Swagger 2.0 сначала нужно преобразовать.

Исходный текст

SKILL.md · MIT
---
name: openapi-to-application-java-spring-boot
description: 'Generate a Spring Boot (Java) application from an OpenAPI 3 specification using the spec-first approach: openapi-generator (Maven or Gradle) produces API interfaces and DTOs, you implement controllers, services, persistence, security and tests. Use when asked to build, scaffold or implement a Spring Boot API from an OpenAPI/Swagger file.'
---

# Spring Boot application from an OpenAPI spec

Spec-first: the OpenAPI file is the source of truth. Generate **interfaces and DTOs only** at build time (never commit generated code), then hand-write the implementation. Verified with Spring Boot 4.0.8 and 4.1.1, openapi-generator 7.26.0 (Maven plugin, Gradle Groovy and Kotlin DSL), JDK 21+.

## Step 0: Detect and gather

- Existing `pom.xml` / `build.gradle(.kts)`: keep its build tool and Spring Boot version, **never upgrade implicitly**, add the generator to it. Otherwise create the project with the `create-spring-boot-java-project` skill (dependencies: `web`, `validation`, `actuator`; add `data-jpa`, `postgresql`, `security` only if needed).
- Get the spec (file, URL or pasted) and save it as `src/main/resources/openapi/<name>.yaml`. Accept 3.0.x and 3.1.x; Swagger 2.0 must be converted first.
- Ask only what the spec does not answer: persistence (in-memory vs database), authentication, package name.

## Step 1: Review the spec

Check unique `operationId`s (they become method names), `tags` (they become one interface each), reusable `components/schemas`, `required` lists, validation constraints (`minLength`, `maximum`, `pattern`), error responses and `securitySchemes`. Flag gaps and fix the spec rather than the generated code.

## Step 2: Configure the generator

Pin the version in a property; check the latest on Maven Central or the [generator docs](https://openapi-generator.tech/docs/generators/spring) before changing it.

Maven (`pom.xml`, in `<build><plugins>`, before `spring-boot-maven-plugin`):

```xml
<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>${openapi-generator.version}</version> <!-- 7.26.0 -->
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/openapi/petstore.yaml</inputSpec>
        <generatorName>spring</generatorName>
        <apiPackage>com.example.petstore.api</apiPackage>
        <modelPackage>com.example.petstore.api.model</modelPackage>
        <generateSupportingFiles>false</generateSupportingFiles>
        <configOptions>
          <interfaceOnly>true</interfaceOnly>
          <requestMappingMode>api_interface</requestMappingMode>
          <useSpringBoot4>true</useSpringBoot4>
          <useJackson3>true</useJackson3>
          <useSpringBuiltInValidation>true</useSpringBuiltInValidation>
          <useTags>true</useTags>
          <skipDefaultInterface>true</skipDefaultInterface>
          <openApiNullable>false</openApiNullable>
          <documentationProvider>none</documentationProvider>
          <annotationLibrary>none</annotationLibrary>
        </configOptions>
      </configuration>
    </execution>
  </executions>
</plugin>
```

Gradle (Groovy DSL; plugin `id 'org.openapi.generator' version '7.26.0'`):

```groovy
openApiGenerate {
  generatorName = 'spring'
  inputSpec = "$projectDir/src/main/resources/openapi/petstore.yaml".toString()
  outputDir = layout.buildDirectory.dir('generated/openapi').get().asFile.path
  apiPackage = 'com.example.petstore.api'
  modelPackage = 'com.example.petstore.api.model'
  generateApiTests = false
  generateModelTests = false
  generateSupportingFiles = false
  configOptions = [interfaceOnly: 'true', requestMappingMode: 'api_interface', useSpringBoot4: 'true', useJackson3: 'true', useSpringBuiltInValidation: 'true', useTags: 'true',
    skipDefaultInterface: 'true', openApiNullable: 'false', documentationProvider: 'none', annotationLibrary: 'none']
}
sourceSets.main.java.srcDir layout.buildDirectory.dir('generated/openapi/src/main/java')
tasks.named('compileJava') { dependsOn 'openApiGenerate' }
```

Gradle (Kotlin DSL; plugin `id("org.openapi.generator") version "7.26.0"`, resolved from the Gradle plugin portal, so keep `gradlePluginPortal()` in `pluginManagement`):

```kotlin
openApiGenerate {
    generatorName.set("spring")
    inputSpec.set("$projectDir/src/main/resources/openapi/petstore.yaml")
    outputDir.set(layout.buildDirectory.dir("generated/openapi").get().asFile.path)
    apiPackage.set("com.example.petstore.api")
    modelPackage.set("com.example.petstore.api.model")
    generateApiTests.set(false)
    generateModelTests.set(false)
    generateSupportingFiles.set(false)
    configOptions.set(mapOf("interfaceOnly" to "true", "requestMappingMode" to "api_interface", "useSpringBoot4" to "true", "useJackson3" to "true", "useSpringBuiltInValidation" to "true", "useTags" to "true",
        "skipDefaultInterface" to "true", "openApiNullable" to "false", "documentationProvider" to "none", "annotationLibrary" to "none"))
}
sourceSets.main { java.srcDir(layout.buildDirectory.dir("generated/openapi/src/main/java")) }
tasks.compileJava { dependsOn("openApiGenerate") }
```

Option notes:

- **Spring Boot 3.x**: drop `useSpringBoot4` and `useJackson3` (`useSpringBoot3=true` is the default). Boot 4 needs both options; Jackson 3 is only allowed with `useSpringBoot4`.
- **Request-parameter validation:** for Boot 3.2+/4 (Framework 6.1+), keep `useSpringBuiltInValidation=true` in all build-tool configurations. It omits type-level `@Validated` from generated API interfaces so MVC handles constrained query/path parameters through `HandlerMethodValidationException`. For Boot 3.0/3.1, leave this option `false` to retain AOP validation and explicitly map request-parameter `ConstraintViolationException` to HTTP 400 with the spec's error body. Do not blanket-map service-layer constraint violations to 400. Never patch generated interfaces to change validation behavior.
- **Base paths:** `requestMappingMode=api_interface` puts the class-level base-path mapping on the interface when no controller is generated. For `servers: [{url: /v1}]` and path `/pets`, verify `/v1/pets`; do not add the same `/v1` prefix again through controller mappings, `server.servlet.context-path` or proxy rewriting.
- `interfaceOnly=true` generates `<Tag>Api` interfaces (with `@RequestMapping`/validation annotations) and models. `delegatePattern=true` (instead) generates controllers calling a `<Tag>ApiDelegate` you implement; prefer `interfaceOnly`, it is simpler. If you use `delegatePattern` (verified on Boot 4.1.1): drop `skipDefaultInterface` (it breaks the generated delegate, compile errors); generate only `ApiUtil.java` as supporting file, otherwise the default delegate methods fail with `cannot find symbol ApiUtil` and a full set of supporting files adds an `OpenApiGeneratorApplication` main class (`Unable to find a single main class` in `bootJar`): Maven `<supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>` instead of `<generateSupportingFiles>false</generateSupportingFiles>`, Gradle `globalProperties = [apis: '', models: '', supportingFiles: 'ApiUtil.java']`. The generated `<Tag>ApiController` is a `@Controller` in `apiPackage`: it must be under the `@SpringBootApplication` package (e.g. `com.example.demo.api`), otherwise it is not scanned and the endpoints return 404.
- `documentationProvider=none` and `annotationLibrary=none` avoid pulling springdoc/swagger annotations into the generated code. Serving the spec/Swagger UI is optional: add `org.springdoc:springdoc-openapi-starter-webmvc-ui` (3.x line for Boot 4, 2.8.x for Boot 3) only if requested; verified with springdoc 3.1.1 on Boot 4.1.1 (`/v3/api-docs` returns OpenAPI 3.1 JSON, `/swagger-ui/index.html` returns 200).
- `openApiNullable=false` avoids the `jackson-databind-nullable` dependency; keep it `true` only if the spec has PATCH semantics with nullable fields.
- Generated models use `jakarta.validation`: `spring-boot-starter-validation` must be on the classpath. Required properties become constructor arguments **in generated order**; read the generated class in `target/generated-sources/openapi` (or `build/generated/openapi`) before calling constructors.
- Use `<importMappings>`/`<typeMappings>` only when a schema must map to an existing class.

## Step 3: Implement

- One `@RestController` per generated `<Tag>Api` interface, `implements` it, no extra mapping annotations (they are inherited from the interface). Keep controllers thin; put logic in `@Service` classes and return DTOs, not entities. Map entities to generated DTOs explicitly (a MapStruct mapper if the project already uses it).
- Persistence: in-memory only when asked; otherwise Spring Data JPA entities and repositories separate from the generated DTOs, PostgreSQL via Docker Compose for dev, and schema handling per the schema management rule of the `java-hibernate-jpa` skill (Flyway or Liquibase for production). See the `java-springboot` skill.
- Errors: use `@RestControllerAdvice` to preserve each operation's declared error status, media type and response schema, including validation failures. Handle `MethodArgumentNotValidException` for request bodies and, on Boot 3.2+/4, `HandlerMethodValidationException` for query/path parameters; override the corresponding handlers when extending `ResponseEntityExceptionHandler`. Return RFC 9457 `ProblemDetail` only when the spec declares it; otherwise return the declared error DTO instead of Spring's default validation response. If error responses are missing or ambiguous, ask before changing the contract rather than imposing Problem Details or a blanket 400/404/409 policy.
- Security: map `securitySchemes` with the `spring-security` skill (JWT resource server, API key filter, method security). Do not generate `useSpringSecurityPreAuthorize` unless scopes are declared.
- Never edit generated sources; change the spec or the generator options and rebuild.

## Step 4: Test and verify

- Follow the `spring-boot-testing` skill: `@WebMvcTest` slices per controller (mock the service), `@SpringBootTest` + MockMvc for the happy path and one validation failure per write operation, Testcontainers with `@ServiceConnection` for database code (see `java-testcontainers`).
- Cover every operation in the spec: success, not found, invalid input. Test invalid constrained query/path parameters as well as invalid request bodies. For error responses, including validation failures, assert the declared status, content type and body schema, not just the status code. Optionally assert the spec itself stays valid in CI with `openapi-generator validate -i <spec>` or by letting the build fail on generation errors.
- Run `./mvnw verify` or `./gradlew build`, then start the app and `curl` one endpoint plus `/actuator/health`. Include an endpoint from a spec with a non-root server URL and assert its full path, so a missing or duplicated base prefix is caught.
- Report: spec issues found, generator version and options, files written, anything deferred.

© github · MIT · github/awesome-copilot

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
spring-boot-openapi-documentation giuseppe-trisciuoglio Скилл spring-boot-openapi-documentation помогает агенту настроить SpringDoc OpenAPI 3.0 и Swagger UI в проекте на Spring Boot 3.x и разметить эндпоинты аннотациями. CX Codex +1 4 200установок 302-frameworks-spring-boot-rest Juan Antonio Breña Moral Скилл 302-frameworks-spring-boot-rest для проектирования и разбора REST API на Spring Boot: методы, коды ответов, DTO, версионирование, пагинация, ошибки по RFC 7807. CX Codex +1 420установок devkit.java.generate-docs Giuseppe Trisciuoglio Команда devkit.java.generate-docs генерирует документацию для проектов на Java и Spring Boot: спецификации OpenAPI, архитектурные схемы, Javadoc и файлы README. CX Codex +1 ★ 372звёзд репо spring-boot Mindrally Задаёт агенту стиль кода на Spring Boot: REST-контроллеры, тесты, безопасность, сборка и деплой. Обеспечивает единообразие в проектах на Java. CX Codex +1 881установок 301-frameworks-spring-boot-core Juan Antonio Breña Moral Скилл 301-frameworks-spring-boot-core настраивает правила ревью и рефакторинга кода на Spring Boot 4.0.x. Помогает внедрять зависимости через конструктор и валидировать конфигурацию. CX Codex +1 421установок java-spring-boot pluginagentmarketplace Скилл java-spring-boot помогает создавать бэкенд на Spring Boot 3: настраивать REST API, аутентификацию через Spring Security, доступ к базам через Spring Data и мониторинг Actuator. CX Codex +1 11 800установок

Из того же набора993

Весь набор →
scout-issue Скилл scout-issue для GitHub Copilot подбирает GitHub issues для вклада в открытые проекты. Он спрашивает об опыте, навыках, времени и типе вклада, затем ранжирует подходящие задачи. CX Codex +1 ★ 41 430звёзд репо sap-cloud-integration Помогает писать и разбирать iFlow в SAP Cloud Integration. Срабатывает при работе с CPI-скриптами Groovy, настройками обмена и ошибками адаптеров. CX Codex +1 ★ 41 430звёзд репо pr-artifact-explorer Скилл pr-artifact-explorer для GitHub Copilot открывает GitHub PR, issues, запуски workflow, Actions-артефакты и веб-превью в общей панели. Он включается по запросу показать или изучить эти материалы. CX Codex +1 ★ 41 430звёзд репо ponder Скилл ponder для GitHub Copilot запускает цикл повторных проходов оценки проекта, пока выводы модели не перестанут меняться. Проверяет полное покрытие всех модулей без пропуска файлов. CX Codex +1 ★ 41 430звёзд репо on-device-delegate Скилл on-device-delegate для GitHub Copilot передаёт объёмное чтение файлов локальному агенту. Основная сессия экономит контекст облачной модели при разборе логов или поиске фактов. CX Codex +1 ★ 41 430звёзд репо markdown-to-word-mermaid Скилл markdown-to-word-mermaid для GitHub Copilot превращает Markdown с диаграммами Mermaid в документ Word. Диаграммы сохраняются в SVG с PNG-резервом, а крупные изображения размещаются с учётом страниц. CX Codex +1 ★ 41 430звёзд репо logicapps-custom-code-net10-migration Скилл logicapps-custom-code-net10-migration для GitHub Copilot переводит проекты кастомного кода Azure Logic Apps Standard с .NET 8 на .NET 10. Настраивает конфигурацию проектов, сборку и локальную отладку в VS Code. CX Codex +1 ★ 41 430звёзд репо lightweight-charts-react-components Скилл lightweight-charts-react-components для GitHub Copilot помогает добавлять и чинить финансовые графики на React с lightweight-charts. Включается по запросу о TradingView-графиках, пакетах lightweight-charts или их возможностях. CX Codex +1 ★ 41 430звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой