tongchengopensource / smart-doc-gradle-plugin Goto Github PK
View Code? Open in Web Editor NEWsmart-doc gradle plugin
License: Apache License 2.0
smart-doc gradle plugin
License: Apache License 2.0
Documentation is generated normally.
正常生成文档
Execution failed for task ':api-service:smartDocRestHtml'.
> Configuration with name 'compile' not found.
Adapt to the gradle
plugin java-library
.
适配gradle
插件java-library
Documentation cannot be generated.
During the use of the plugin, for an API definition like the one below, the return value instance is defined using the @response tag.
使用插件过程中,对一个类似下面的接口定义,使用@response标签定义了返回值实例。
/**
* 数据版本
*
* @return 数据月份,如202301|com.common.Response<java.lang.String>
* @response {
* "code": 0,
* "msg": "success!",
* "data": "1.0.0"
* }
*/
@GetMapping("month")
public Response<String> dataVersion() {
return null;
}
The Response structure is relatively simple, with standard fields for status codes and descriptions.
@Data
public class Response<T> implements Serializable {
private int code;
private String msg;
private T data;
}
The documents generated by the smartDocOpenApi and smartDocMarkdown tasks meet expectations, using examples from the comments.
使用smartDocOpenApi、smartDocMarkdown任务生成的文档符合预期,使用了注释中的示例
{
"examples": {
"json": {
"summary": "test data",
"value": "{\n \"code\": 0,\n \"msg\": \"success!\",\n \"data\": \"202301\"\n}"
}
}
}
Executing the torna task, the expected imported document should also use examples from the comments, but in reality, it generates random return value examples.
执行torna任务,预期导入的文档也应当使用注释中的示例,但是实际生成了随机的返回值示例。
When executing the torna task, random return values were generated without using the examples in the comments.
实际执行torna任务时,生成了随机的返回值,没有使用注释中的示例。
After migrating my project to Gradle and using the plugin to build the documentation, I kept encountering errors without being able to identify the cause. Therefore, I started over with building the project from scratch, adding dependencies bit by bit, and that's when I discovered the issue. Below are the configurations of my project.
settings.gradle
rootProject.name = "test-smart-project"
build.gradle
plugins {
id 'java'
id("org.springframework.boot") version "2.5.3"
id("io.spring.dependency-management") version "1.0.11.RELEASE"
id("com.github.shalousun.smart-doc") version "2.3.4"
}
group = "com.xzcode"
version = "0.1.0-SNAPSHOT"
repositories {
mavenLocal()
mavenCentral()
}
smartdoc {
configFile = file("src/main/resources/smart-doc.json")
}
java {
sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
}
dependencies {
implementation "org.springframework.boot:spring-boot-starter-web"
// implementation "org.springframework.boot:spring-boot-starter-data-jpa"
implementation 'com.h2database:h2:2.0.202'
testImplementation "org.junit.jupiter:junit-jupiter-api"
testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine"
}
There's no other code; it's just the addition of a class.
src/main/java/com/mrwang/mp/Testapplication.java
@SpringBootApplication
@RestController
@RequestMapping("test")
public class TestApplication {
public static void main(String[] args) {
SpringApplication.run(TestApplication.class, args);
}
/**
* A simple test
*/
@GetMapping
public String test() {
return "wo de";
}
}
Once I added // implementation "org.springframework.boot:spring-boot-starter-data-jpa"
to the project, an error would occur during the documentation build, with the prompt Error: could not match input.
However, if I removed implementation "org.springframework.boot:spring-boot-starter-data-jpa"
from the project, everything went smoothly.
要是支持安卓就香了
My project structure is somewhat unique, with the following configurations:
subprojects {
apply(plugin = "java")
java {
sourceSets {
main {
java { setSrcDirs(listOf("java")) }
resources { setSrcDirs(listOf("resources")) }
}
test {
java { setSrcDirs(listOf("test")) }
resources { setSrcDirs(listOf("testResources")) }
}
}
}
}
The project structure is roughly like this:
The relevant configurations for smart-doc:
plugins {
java
id("org.springframework.boot") version "3.0.2"
id("io.spring.dependency-management") version "1.1.0"
@Suppress("SpellCheckingInspection")
id("com.github.shalousun.smart-doc") version "2.2.3"
}
smartdoc {
configFile = file("resources/smart-doc.json")
}
The smart-doc.json is just copied from the official website; there are no special configurations.
After running the command to generate the documentation, onlyAfter running the command to generate the documentation, only read, and not a single only the project information could be read, and not a single interface was detected.
Here, I'll use smartDocOpenApi
as an example:
21:24:11: 正在执行 'smartDocOpenApi'…
> Task :yun-baidu:baidu-image-process:compileJava UP-TO-DATE
> Task :application:app-image-process-server:compileJava UP-TO-DATE
> Task :application:app-image-process-server:smartDocOpenApi
Smart-doc Starting Create API Documentation.
The loaded local code path is C:\code\开放平台接入\application\app-image-process-server\src\main\java
The loaded local code path is C:\code\开放平台接入\yun-baidu\baidu-image-process\src/main/java
syntax error @[32,18] in jar:file:/C:/env/data/gradle/caches/modules-2/files-2.1/pub.syrm.tool/core/1.0-SNAPSHOT/c04be76fdd9e5f799c5014182822b11f50d8cff4/core-1.0-SNAPSHOT-sources.jar!/pub/syrm/tool/model/Tuple.java
syntax error @[37,8] in jar:file:/C:/env/data/gradle/caches/modules-2/files-2.1/org.springframework/spring-core/6.0.4/c82cc3af52dbea3aa7841ca8cbe0959bc395e08e/spring-core-6.0.4-sources.jar!/org/springframework/core/io/support/PropertySourceDescriptor.java
syntax error @[349,27] in jar:file:/C:/env/data/gradle/caches/modules-2/files-2.1/org.springframework/spring-core/6.0.4/c82cc3af52dbea3aa7841ca8cbe0959bc395e08e/spring-core-6.0.4-sources.jar!/org/springframework/util/ConcurrentLruCache.java
API Documentation output to C:\code\开放平台接入\application\app-image-process-server/resources/static/doc
BUILD SUCCESSFUL in 2s
3 actionable tasks: 1 executed, 2 up-to-date
21:24:13: 执行完成 'smartDocOpenApi'。
The problem is uncertain at the moment, but I suspect that you've hardcoded the src/main/java
path without taking the configuration from sourceSets
.
If it's confirmed that there's no issue with supporting sourceSets
, I'll create a minimal reproduction case.
以下是我的build.gradle.kts
plugins {
`java-library`
id("org.springframework.boot") version "2.5.3"
id("io.spring.dependency-management") version "1.0.11.RELEASE"
id("cz.habarta.typescript-generator") version "2.32.889"
id("com.github.shalousun.smart-doc") version "2.2.2"
}
smartdoc {
configFile = file("src/main/resources/smart-doc.json")
// Cannot access 'include': it is package-private in 'SmartDocPluginExtension'
include("com.dm:dm-common")
}
在这里提示包的可见性问题。是不是应该修改一下插件响应方法的可见性,或者是别的什么方式?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.