-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: add tasks for OpenAPI docs and api-client code generation (#16)
### What this PR does?
实现了两个 tasks，用于为插件项目生成 OpenAPI docs 和 API Client
- `generateOpenApiDocs`: 启动一个 Halo 作为 API Docs Server 并根据用户配置的 groupedApiMappings 来下载 Open API 的 json 文件到指定目录
- `generateApiClient` 根据 groupedApiMappings 指定的文件名称和其他配置来生成 API Client 到前端模块的项目中
**使用方式：**
在 build.gradle 中配置
```kotlin
haloPlugin {
// 可以配置 configurationPropertiesFile 来指定插件需要的配置文件如应用市场插件
// configurationPropertiesFile = file("${projectDir}/test.yaml")
openApi {
outputDir = file("$rootDir/api-docs/openapi/v3_0")
// 用于定义 API 分组规则
groupingRules {
// 此名称为 group name，定义后 groupedApiMappings 中的 /v3/api-docs/ 后的名称需要与之相同，要避免与 halo 中已经存在的 group 相同避免生成后出现与插件无关的 API
staticPagesExtensionV1alpha1Api {
// 分组显示名称
displayName = 'Extension API for Static Pages'
// 分组的 API 规则
pathsToMatch = ['/apis/staticpage.halo.run/v1alpha1/**']
}
}
groupedApiMappings = [
'/v3/api-docs/staticPagesExtensionV1alpha1Api': 'staticPagesExtensionV1alpha1Api.json'
]
generator {
// 默认配置可缺省
outputDir = file("${projectDir}/console/src/api/generated")
// 默认配置可缺省
additionalProperties = [
useES6: true,
useSingleRequestParameter: true,
withSeparateModelsAndApi: true,
apiPackage: "api",
modelPackage: "models"
]
// 默认配置可缺省
typeMappings = [
set: "Array"
]
}
}
}
```
**how to test it?**
1. `./gradlew clean build -x check `
2. `./gradlew publishToMavenLocal`
3. 在插件项目中使用此插件 `id "run.halo.plugin.devtools" version "0.0.10-SNAPSHOT"`
4. 配置插件的 `settings.gradle` 中的 repositories 添加 `mavenLocal()`
```release-note
支持生成 API 文档（需升级 Gradle 至 8.3 及以上的版本）
```- Loading branch information
Showing
17 changed files
with
1,066 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,7 @@ | ||
| distributionBase=GRADLE_USER_HOME | ||
| distributionPath=wrapper/dists | ||
| distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip | ||
| distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip | ||
| networkTimeout=10000 | ||
| validateDistributionUrl=true | ||
| zipStoreBase=GRADLE_USER_HOME | ||
| zipStorePath=wrapper/dists |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
45 changes: 45 additions & 0 deletions
45
src/main/java/run/halo/gradle/openapi/ApiClientExtension.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| package run.halo.gradle.openapi; | ||
|
|
||
| import java.util.HashMap; | ||
| import javax.inject.Inject; | ||
| import lombok.Data; | ||
| import lombok.ToString; | ||
| import org.gradle.api.file.DirectoryProperty; | ||
| import org.gradle.api.file.ProjectLayout; | ||
| import org.gradle.api.model.ObjectFactory; | ||
| import org.gradle.api.provider.MapProperty; | ||
| import org.gradle.api.provider.Property; | ||
|
|
||
| @Data | ||
| @ToString | ||
| public class ApiClientExtension { | ||
| private DirectoryProperty outputDir; | ||
| private Property<String> generatorName; | ||
| private MapProperty<String, Object> additionalProperties; | ||
| private MapProperty<String, String> typeMappings; | ||
|
|
||
| @Inject | ||
| public ApiClientExtension(ObjectFactory objectFactory, ProjectLayout layout) { | ||
| this.outputDir = objectFactory.directoryProperty(); | ||
| this.generatorName = objectFactory.property(String.class); | ||
| this.additionalProperties = objectFactory.mapProperty(String.class, Object.class); | ||
| this.typeMappings = objectFactory.mapProperty(String.class, String.class); | ||
|
|
||
| // init | ||
| outputDir.convention(layout.getProjectDirectory() | ||
| .dir("console/src/api/generated")); | ||
| this.generatorName.convention("typescript-axios"); | ||
|
|
||
| var properties = new HashMap<String, Object>(); | ||
| properties.put("useES6", true); | ||
| properties.put("useSingleRequestParameter", true); | ||
| properties.put("withSeparateModelsAndApi", true); | ||
| properties.put("apiPackage", "api"); | ||
| properties.put("modelPackage", "models"); | ||
| this.additionalProperties.convention(properties); | ||
|
|
||
| var typeMappings = new HashMap<String, String>(); | ||
| typeMappings.put("set", "Array"); | ||
| this.typeMappings.convention(typeMappings); | ||
| } | ||
| } |
Oops, something went wrong.