mirror of
https://gitee.com/bookshelfplus/bookshelfplus
synced 2025-09-13 04:01:40 +08:00
添加Swagger2生成Api文档测试类，以及adoc转html
This commit is contained in:
18
bookshelfplus/.idea/runConfigurations/_SwaggerApiDocGeneratorTest.xml
generated
Normal file
18
bookshelfplus/.idea/runConfigurations/_SwaggerApiDocGeneratorTest.xml
generated
Normal file
@@ -0,0 +1,18 @@
|
||||
<component name="ProjectRunConfigurationManager">
|
||||
<configuration default="false" name="生成接口文档文件 SwaggerApiDocGeneratorTest" type="JUnit" factoryName="JUnit">
|
||||
<module name="bookshelfplus" />
|
||||
<extension name="coverage">
|
||||
<pattern>
|
||||
<option name="PATTERN" value="plus.bookshelf.*" />
|
||||
<option name="ENABLED" value="true" />
|
||||
</pattern>
|
||||
</extension>
|
||||
<option name="PACKAGE_NAME" value="plus.bookshelf" />
|
||||
<option name="MAIN_CLASS_NAME" value="plus.bookshelf.SwaggerApiDocGeneratorTest" />
|
||||
<option name="METHOD_NAME" value="" />
|
||||
<option name="TEST_OBJECT" value="class" />
|
||||
<method v="2">
|
||||
<option name="Make" enabled="true" />
|
||||
</method>
|
||||
</configuration>
|
||||
</component>
|
||||
@@ -1,5 +1,5 @@
|
||||
<component name="ProjectRunConfigurationManager">
|
||||
<configuration default="false" name="bookshelfplus [mybatis-generator:generate]" type="MavenRunConfiguration" factoryName="Maven" nameIsGenerated="true">
|
||||
<configuration default="false" name="生成数据库映射文件 bookshelfplus [mybatis-generator:generate]" type="MavenRunConfiguration" factoryName="Maven">
|
||||
<MavenSettings>
|
||||
<option name="myGeneralSettings" />
|
||||
<option name="myRunnerSettings" />
|
||||
1
bookshelfplus/convertAdocIntoHtml.sh
Normal file
1
bookshelfplus/convertAdocIntoHtml.sh
Normal file
@@ -0,0 +1 @@
|
||||
mvn asciidoctor:process-asciidoc
|
||||
329
bookshelfplus/docs/asciidoc/generated/all.adoc
Normal file
329
bookshelfplus/docs/asciidoc/generated/all.adoc
Normal file
@@ -0,0 +1,329 @@
|
||||
= 书栖网 服务端接口文档
|
||||
|
||||
|
||||
[[_overview]]
|
||||
== 概览
|
||||
RESTful API | bookshelf.plus
|
||||
|
||||
|
||||
=== 版本信息
|
||||
[%hardbreaks]
|
||||
__版本__ : 1.0
|
||||
|
||||
|
||||
=== URI scheme
|
||||
[%hardbreaks]
|
||||
__域名__ : localhost:8090
|
||||
__基础路径__ : /api
|
||||
|
||||
|
||||
=== 标签
|
||||
|
||||
* book-controller : Book Controller
|
||||
* status-controller : Status Controller
|
||||
* user-controller : User Controller
|
||||
|
||||
|
||||
|
||||
|
||||
[[_paths]]
|
||||
== 资源
|
||||
|
||||
[[_book-controller_resource]]
|
||||
=== Book-controller
|
||||
Book Controller
|
||||
|
||||
|
||||
[[_getusingget]]
|
||||
==== 获取书籍信息
|
||||
....
|
||||
GET /book/get
|
||||
....
|
||||
|
||||
|
||||
===== 说明
|
||||
获取书籍信息
|
||||
|
||||
|
||||
===== 参数
|
||||
|
||||
[options="header", cols=".^2,.^3,.^9,.^4"]
|
||||
|===
|
||||
|类型|名称|说明|类型
|
||||
|**Query**|**id** +
|
||||
__必填__|id|integer (int32)
|
||||
|===
|
||||
|
||||
|
||||
===== 响应
|
||||
|
||||
[options="header", cols=".^2,.^14,.^4"]
|
||||
|===
|
||||
|HTTP代码|说明|类型
|
||||
|**200**|OK|<<_bookvo,BookVO>>
|
||||
|**401**|Unauthorized|无内容
|
||||
|**403**|Forbidden|无内容
|
||||
|**404**|Not Found|无内容
|
||||
|===
|
||||
|
||||
|
||||
===== 生成
|
||||
|
||||
* `*/*`
|
||||
|
||||
|
||||
===== HTTP请求示例
|
||||
|
||||
====== 请求 path
|
||||
----
|
||||
/book/get
|
||||
----
|
||||
|
||||
|
||||
====== 请求 query
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"id" : 0
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
===== HTTP响应示例
|
||||
|
||||
====== 响应 200
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"author" : "string",
|
||||
"bookName" : "string",
|
||||
"category" : {
|
||||
"description" : "string",
|
||||
"id" : 0,
|
||||
"isShow" : true,
|
||||
"level" : 0,
|
||||
"name" : "string",
|
||||
"order" : 0,
|
||||
"parentId" : 0
|
||||
},
|
||||
"copyright" : "string",
|
||||
"description" : "string",
|
||||
"id" : 0,
|
||||
"language" : "string",
|
||||
"publishingHouse" : "string",
|
||||
"thumbnail" : "string"
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
[[_status-controller_resource]]
|
||||
=== Status-controller
|
||||
Status Controller
|
||||
|
||||
|
||||
[[_getusingget_1]]
|
||||
==== 线程CPU占用时间
|
||||
....
|
||||
GET /status/getProcessCpu
|
||||
....
|
||||
|
||||
|
||||
===== 说明
|
||||
获取服务器当前线程CPU占用时间。此方法通过统计线程CPU占用时间来统计当前进程占用CPU情况。
|
||||
|
||||
|
||||
===== 响应
|
||||
|
||||
[options="header", cols=".^2,.^14,.^4"]
|
||||
|===
|
||||
|HTTP代码|说明|类型
|
||||
|**200**|OK|object
|
||||
|**401**|Unauthorized|无内容
|
||||
|**403**|Forbidden|无内容
|
||||
|**404**|Not Found|无内容
|
||||
|===
|
||||
|
||||
|
||||
===== 生成
|
||||
|
||||
* `*/*`
|
||||
|
||||
|
||||
===== HTTP请求示例
|
||||
|
||||
====== 请求 path
|
||||
----
|
||||
/status/getProcessCpu
|
||||
----
|
||||
|
||||
|
||||
===== HTTP响应示例
|
||||
|
||||
====== 响应 200
|
||||
[source,json]
|
||||
----
|
||||
"object"
|
||||
----
|
||||
|
||||
|
||||
[[_user-controller_resource]]
|
||||
=== User-controller
|
||||
User Controller
|
||||
|
||||
|
||||
[[_loginusingpost]]
|
||||
==== 用户登录
|
||||
....
|
||||
POST /user/login
|
||||
....
|
||||
|
||||
|
||||
===== 说明
|
||||
传入用户名，以及密码的MD5值，进行登录
|
||||
|
||||
|
||||
===== 参数
|
||||
|
||||
[options="header", cols=".^2,.^3,.^9,.^4"]
|
||||
|===
|
||||
|类型|名称|说明|类型
|
||||
|**FormData**|**encryptpwd** +
|
||||
__必填__|encryptpwd|string
|
||||
|**FormData**|**username** +
|
||||
__必填__|username|string
|
||||
|===
|
||||
|
||||
|
||||
===== 响应
|
||||
|
||||
[options="header", cols=".^2,.^14,.^4"]
|
||||
|===
|
||||
|HTTP代码|说明|类型
|
||||
|**200**|OK|<<_uservo,UserVO>>
|
||||
|**201**|Created|无内容
|
||||
|**401**|Unauthorized|无内容
|
||||
|**403**|Forbidden|无内容
|
||||
|**404**|Not Found|无内容
|
||||
|===
|
||||
|
||||
|
||||
===== 消耗
|
||||
|
||||
* `application/x-www-form-urlencoded`
|
||||
|
||||
|
||||
===== 生成
|
||||
|
||||
* `*/*`
|
||||
|
||||
|
||||
===== HTTP请求示例
|
||||
|
||||
====== 请求 path
|
||||
----
|
||||
/user/login
|
||||
----
|
||||
|
||||
|
||||
====== 请求 formData
|
||||
[source,json]
|
||||
----
|
||||
"string"
|
||||
----
|
||||
|
||||
|
||||
===== HTTP响应示例
|
||||
|
||||
====== 响应 200
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"avatar" : "string",
|
||||
"id" : 0,
|
||||
"nickname" : "string",
|
||||
"phone" : "string",
|
||||
"userIdentity" : "string",
|
||||
"username" : "string"
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
|
||||
[[_definitions]]
|
||||
== 定义
|
||||
|
||||
[[_bookvo]]
|
||||
=== BookVO
|
||||
|
||||
[options="header", cols=".^3,.^11,.^4"]
|
||||
|===
|
||||
|名称|说明|类型
|
||||
|**author** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**bookName** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**category** +
|
||||
__可选__|**样例** : `"<<_categorymodel>>"`|<<_categorymodel,CategoryModel>>
|
||||
|**copyright** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**description** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**id** +
|
||||
__可选__|**样例** : `0`|integer (int32)
|
||||
|**language** +
|
||||
__可选__|**样例** : `"string"`|enum (SIMPLIFIED_CHINESE, ENGLISH, TRADITIONAL_CHINESE)
|
||||
|**publishingHouse** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**thumbnail** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|===
|
||||
|
||||
|
||||
[[_categorymodel]]
|
||||
=== CategoryModel
|
||||
|
||||
[options="header", cols=".^3,.^11,.^4"]
|
||||
|===
|
||||
|名称|说明|类型
|
||||
|**description** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**id** +
|
||||
__可选__|**样例** : `0`|integer (int32)
|
||||
|**isShow** +
|
||||
__可选__|**样例** : `true`|boolean
|
||||
|**level** +
|
||||
__可选__|**样例** : `0`|integer (int32)
|
||||
|**name** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**order** +
|
||||
__可选__|**样例** : `0`|integer (int32)
|
||||
|**parentId** +
|
||||
__可选__|**样例** : `0`|integer (int32)
|
||||
|===
|
||||
|
||||
|
||||
[[_uservo]]
|
||||
=== UserVO
|
||||
|
||||
[options="header", cols=".^3,.^11,.^4"]
|
||||
|===
|
||||
|名称|说明|类型
|
||||
|**avatar** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**id** +
|
||||
__可选__|**样例** : `0`|integer (int32)
|
||||
|**nickname** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**phone** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**userIdentity** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|**username** +
|
||||
__可选__|**样例** : `"string"`|string
|
||||
|===
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
1187
bookshelfplus/docs/asciidoc/html/all.html
Normal file
1187
bookshelfplus/docs/asciidoc/html/all.html
Normal file
File diff suppressed because it is too large
Load Diff
@@ -28,7 +28,7 @@
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
<artifactId>junit</artifactId>
|
||||
<version>4.11</version>
|
||||
<version>4.13</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
@@ -116,12 +116,12 @@
|
||||
<dependency>
|
||||
<groupId>io.springfox</groupId>
|
||||
<artifactId>springfox-swagger2</artifactId>
|
||||
<version>2.6.1</version>
|
||||
<version>2.9.2</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.springfox</groupId>
|
||||
<artifactId>springfox-swagger-ui</artifactId>
|
||||
<version>2.6.1</version>
|
||||
<version>2.9.2</version>
|
||||
</dependency>
|
||||
<!--前面引入过这个包-->
|
||||
<!--<dependency>-->
|
||||
@@ -133,6 +133,21 @@
|
||||
<artifactId>spring-boot-starter-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Swagger 生成离线静态API文档
|
||||
refer: https://blog.csdn.net/aiguoguo000/article/details/105681606
|
||||
-->
|
||||
<dependency>
|
||||
<groupId>io.github.swagger2markup</groupId>
|
||||
<artifactId>swagger2markup</artifactId>
|
||||
<version>1.3.1</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.asciidoctor</groupId>
|
||||
<artifactId>asciidoctorj-pdf</artifactId>
|
||||
<version>1.5.0-alpha.10.1</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
@@ -218,6 +233,44 @@
|
||||
</configurationFile>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
<!-- Swagger 生成离线静态API文档
|
||||
refer: https://blog.csdn.net/aiguoguo000/article/details/105681606
|
||||
-->
|
||||
<plugin>
|
||||
<groupId>io.github.swagger2markup</groupId>
|
||||
<artifactId>swagger2markup-maven-plugin</artifactId>
|
||||
<version>1.3.1</version>
|
||||
<configuration>
|
||||
<swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
|
||||
<outputDir>src/docs/asciidoc/generated</outputDir>
|
||||
<config>
|
||||
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
|
||||
</config>
|
||||
</configuration>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.asciidoctor</groupId>
|
||||
<artifactId>asciidoctor-maven-plugin</artifactId>
|
||||
<version>1.5.6</version>
|
||||
<configuration>
|
||||
<!--asciidoc文件目录-->
|
||||
<sourceDirectory>docs/asciidoc/generated</sourceDirectory>
|
||||
<!---生成html的路径-->
|
||||
<outputDirectory>docs/asciidoc/html</outputDirectory>
|
||||
<backend>html</backend>
|
||||
<sourceHighlighter>coderay</sourceHighlighter>
|
||||
<attributes>
|
||||
<!--导航栏在左-->
|
||||
<toc>left</toc>
|
||||
<!--显示层级数-->
|
||||
<!--<toclevels>3</toclevels>-->
|
||||
<!--自动打数字序号-->
|
||||
<sectnums>true</sectnums>
|
||||
</attributes>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
</plugins>
|
||||
</pluginManagement>
|
||||
<plugins>
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
package plus.bookshelf;
|
||||
|
||||
import io.github.swagger2markup.GroupBy;
|
||||
import io.github.swagger2markup.Language;
|
||||
import io.github.swagger2markup.Swagger2MarkupConfig;
|
||||
import io.github.swagger2markup.Swagger2MarkupConverter;
|
||||
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
|
||||
import io.github.swagger2markup.markup.builder.MarkupLanguage;
|
||||
import org.junit.Test;
|
||||
import org.junit.runner.RunWith;
|
||||
import org.springframework.beans.factory.annotation.Value;
|
||||
import org.springframework.boot.test.context.SpringBootTest;
|
||||
import org.springframework.test.context.junit4.SpringRunner;
|
||||
|
||||
import java.net.URL;
|
||||
import java.nio.file.Paths;
|
||||
|
||||
// refer: https://blog.csdn.net/aiguoguo000/article/details/105681606
|
||||
|
||||
@RunWith(SpringRunner.class)
|
||||
//设定端口，申明启动类！！重要
|
||||
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT, classes = App.class)
|
||||
public class SwaggerApiDocGeneratorTest {
|
||||
|
||||
//这个端口号要保持与application.properties中配置的一致
|
||||
@Value("http://localhost:${server.port}${server.servlet.context-path}/v2/api-docs")
|
||||
private String swaggerApiUrl = "http://localhost:8080/v2/api-docs";
|
||||
|
||||
// /**
|
||||
// * 生成AsciiDocs格式文档
|
||||
// *
|
||||
// * @throws Exception
|
||||
// */
|
||||
// @Test
|
||||
// public void generateAsciiDocs() throws Exception {
|
||||
// // 输出Ascii格式
|
||||
// Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
|
||||
// .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//设置生成格式
|
||||
// .withOutputLanguage(Language.ZH)//设置语言中文还是其他语言
|
||||
// .withPathsGroupedBy(GroupBy.TAGS)
|
||||
// .withGeneratedExamples()
|
||||
// .withoutInlineSchema()
|
||||
// .build();
|
||||
// System.out.println(swaggerApiUrl);
|
||||
// //设置swagger-api的json来源
|
||||
// Swagger2MarkupConverter.from(new URL(swaggerApiUrl))
|
||||
// .withConfig(config)
|
||||
// .build()
|
||||
// .toFolder(Paths.get("./docs/asciidoc/generated"));//设置生成文件的路径
|
||||
// }
|
||||
|
||||
// /**
|
||||
// * 生成Markdown格式文档
|
||||
// *
|
||||
// * @throws Exception
|
||||
// */
|
||||
// @Test
|
||||
// public void generateMarkdownDocs() throws Exception {
|
||||
// // 输出Markdown格式
|
||||
// Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
|
||||
// .withMarkupLanguage(MarkupLanguage.MARKDOWN)
|
||||
// .withOutputLanguage(Language.ZH)
|
||||
// .withPathsGroupedBy(GroupBy.TAGS)
|
||||
// .withGeneratedExamples()
|
||||
// .withoutInlineSchema()
|
||||
// .build();
|
||||
//
|
||||
// Swagger2MarkupConverter.from(new URL(swaggerApiUrl))
|
||||
// .withConfig(config)
|
||||
// .build()
|
||||
// .toFolder(Paths.get("./docs/markdown/generated"));
|
||||
// }
|
||||
|
||||
// /**
|
||||
// * 生成Confluence格式文档
|
||||
// *
|
||||
// * @throws Exception
|
||||
// */
|
||||
// @Test
|
||||
// public void generateConfluenceDocs() throws Exception {
|
||||
// // 输出Confluence使用的格式
|
||||
// Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
|
||||
// .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
|
||||
// .withOutputLanguage(Language.ZH)
|
||||
// .withPathsGroupedBy(GroupBy.TAGS)
|
||||
// .withGeneratedExamples()
|
||||
// .withoutInlineSchema()
|
||||
// .build();
|
||||
//
|
||||
// Swagger2MarkupConverter.from(new URL(swaggerApiUrl))
|
||||
// .withConfig(config)
|
||||
// .build()
|
||||
// .toFolder(Paths.get("./docs/confluence/generated"));
|
||||
// }
|
||||
|
||||
/**
|
||||
* 生成AsciiDocs格式文档,并汇总成一个文件
|
||||
*
|
||||
* @throws Exception
|
||||
*/
|
||||
@Test
|
||||
public void generateAsciiDocsToFile() throws Exception {
|
||||
// 输出Ascii到单文件
|
||||
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
|
||||
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
|
||||
.withOutputLanguage(Language.ZH)
|
||||
.withPathsGroupedBy(GroupBy.TAGS)
|
||||
.withGeneratedExamples()
|
||||
.withoutInlineSchema()
|
||||
.build();
|
||||
|
||||
Swagger2MarkupConverter.from(new URL(swaggerApiUrl))
|
||||
.withConfig(config)
|
||||
.build()
|
||||
.toFile(Paths.get("./docs/asciidoc/generated/all"));
|
||||
}
|
||||
|
||||
// /**
|
||||
// * 生成Markdown格式文档,并汇总成一个文件
|
||||
// *
|
||||
// * @throws Exception
|
||||
// */
|
||||
// @Test
|
||||
// public void generateMarkdownDocsToFile() throws Exception {
|
||||
// // 输出Markdown到单文件
|
||||
// Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
|
||||
// .withMarkupLanguage(MarkupLanguage.MARKDOWN)
|
||||
// .withOutputLanguage(Language.ZH)
|
||||
// .withPathsGroupedBy(GroupBy.TAGS)
|
||||
// .withGeneratedExamples()
|
||||
// .withoutInlineSchema()
|
||||
// .build();
|
||||
// Swagger2MarkupConverter.from(new URL(swaggerApiUrl))
|
||||
// .withConfig(config)
|
||||
// .build()
|
||||
// .toFile(Paths.get("./docs/markdown/generated/all"));
|
||||
// }
|
||||
}
|
||||
Reference in New Issue
Block a user