当前位置:网站首页>[solved] how to generate a beautiful static document description page
[solved] how to generate a beautiful static document description page
2022-07-06 01:24:00 【A rookie is a great God】
Often asked recently ITMuch API How to make document pages , Considering the slightly complicated steps , Write a note to summarize .
TIPS
ITMuch API It's a personal video on Muke website 《 Microservices for the future :Spring Cloud Alibaba From entry to advanced 》 Supporting documents for practical projects .
effect
The overall steps
- Integrate Swagger, Generate Swagger Describe the endpoint
/v2/api-docs
- Use
swagger2markup-maven-plugin
, take/v2/api-docs
Generate ASCIIDOC file ; - Use
asciidoctor-maven-plugin
, take ASCIIDOC File conversion to HTML; - Deploy
Integrate Swagger
TIPS
Swagger Is very simple to use , This article will not discuss , Please check the usage of Baidu by yourself .
Commonly used annotations :
- @Api
- @ApiOperation
- @ApiModel
- @ApiModelProperty
Plus dependence
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
<!-- swagger --> <!-- The reason to exclude , It is because if it is not excluded, it will report NumberFormatException Warning of . --> <!-- Reference resources :https://github.com/springfox/springfox/issues/2265--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> </exclusion> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.21</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> </dependency>
To configure Swagger( Configure according to your own needs , The following configuration codes are for reference only )
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
/** * @author itmuch.com */ @Configuration @EnableSwagger2 public class SwaggerConfiguration { /** * swagger Information * * @return Page information */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("ITMuch API") .description("ITMuch API") .termsOfServiceUrl("") .version("1.0.0") .contact(new Contact("", "", "")).build(); } @Bean public Docket customImplementation() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.itmuch")) .paths(PathSelectors.any()) .build() .apiInfo(this.apiInfo()); //.globalOperationParameters(parameters); } }
Interface for Swagger annotation
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
@RestController @RequestMapping("/notices") @RequiredArgsConstructor(onConstructor = @__(@Autowired)) @Api(tags = " Announcement related interfaces ", description = " Announcement related interfaces ") public class NoticeController { /** * Check the latest announcement * * @return Announcement list */ @GetMapping("/newest") @ApiOperation(value = " Check the latest announcement ", notes = " be used for : Notice ") public Notice findNewest() { return new Notice(); } } @AllArgsConstructor @NoArgsConstructor @Builder @Data @ApiModel(" Notice ") public class Notice { /** * ID */ @ApiModelProperty("id") private Integer id; /** * Announcement content */ @ApiModelProperty(" Announcement content ") private String content; ... }
- such , After the application is started , There will be one
/v2/api-docs
Endpoint , Describe your API Information about .
Generate ASCIIDOC
stay pom.xml To add the following :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <build> <plugins> <plugin> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-maven-plugin</artifactId> <version>1.3.1</version> <configuration> <!-- api-docs visit url --> <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput> <!-- Generate as a single document , The output path --> <outputFile>src/docs/asciidoc/generated/all</outputFile> <config> <!-- ascii Format document --> <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage> <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy> </config> </configuration> </plugin> ... |
swagger2markup-maven-plugin
The function of the plug-in is to read http://localhost:8080/v2/api-docs
Information about , Generate ASCIIDOC file . Of course, you can also generate other formats , such as Markdown wait .
This plug-in also has a lot of gestures , See GitHub - Swagger2Markup/swagger2markup-maven-plugin: A Swagger2Markup Maven Plugin
Generate HTML
below , Only need to ASCIIDOC convert to html Just OK 了 , stay pom.xml To add the following :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | <build> <plugins> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <!-- asciidoc Document input path --> <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory> <!-- html Document output path --> <outputDirectory>src/docs/asciidoc/html</outputDirectory> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <!-- html Document format parameters --> <attributes> <doctype>book</doctype> <toc>left</toc> <toclevels>3</toclevels> <numbered></numbered> <hardbreaks></hardbreaks> <sectlinks></sectlinks> <sectanchors></sectanchors> </attributes> </configuration> </plugin> |
asciidoctor-maven-plugin
The plug-in also has many poses , See :GitHub - asciidoctor/asciidoctor-maven-plugin: A Maven plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.
The generated file is in src/docs/asciidoc/html
( Look at the configuration of your plug-in ), Then you can get a NGINX Deployed .
Use
- Start the application
- perform
mvn swagger2markup:convertSwagger2markup
Generate ASCIIDOC - perform
mvn asciidoctor:process-asciidoc
Generate html
边栏推荐
- JVM_ 15_ Concepts related to garbage collection
- Gartner released the prediction of eight major network security trends from 2022 to 2023. Zero trust is the starting point and regulations cover a wider range
- 程序员搞开源,读什么书最合适?
- Modify the ssh server access port number
- Pbootcms plug-in automatically collects fake original free plug-ins
- Dede collection plug-in free collection release push plug-in
- Some features of ECMAScript
- 什么是弱引用?es6中有哪些弱引用数据类型?js中的弱引用是什么?
- 【全網最全】 |MySQL EXPLAIN 完全解讀
- 一图看懂!为什么学校教了你Coding但还是不会的原因...
猜你喜欢
Building core knowledge points
Mathematical modeling learning from scratch (2): Tools
ORA-00030
Leetcode study - day 35
Vulhub vulnerability recurrence 75_ XStream
[机缘参悟-39]:鬼谷子-第五飞箝篇 - 警示之二:赞美的六种类型,谨防享受赞美快感如同鱼儿享受诱饵。
WordPress collection plug-in automatically collects fake original free plug-ins
MATLB | real time opportunity constrained decision making and its application in power system
伦敦银走势中的假突破
Idea sets the default line break for global newly created files
随机推荐
Dede collection plug-in free collection release push plug-in
Loop structure of program (for loop)
Three methods of script about login and cookies
Interview must brush algorithm top101 backtracking article top34
JVM_ 15_ Concepts related to garbage collection
File upload vulnerability test based on DVWA
3D model format summary
程序员搞开源,读什么书最合适?
伦敦银走势中的假突破
什么是弱引用?es6中有哪些弱引用数据类型?js中的弱引用是什么?
2020.2.13
一图看懂!为什么学校教了你Coding但还是不会的原因...
SPIR-V初窺
Leetcode daily question solution: 1189 Maximum number of "balloons"
Fibonacci number
Redis' cache penetration, cache breakdown, cache avalanche
ClickOnce 不支持请求执行级别“requireAdministrator”
Leetcode study - day 35
ORA-00030
Development trend of Ali Taobao fine sorting model