当前位置:网站首页>[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
边栏推荐
- Mlsys 2020 | fedprox: Federation optimization of heterogeneous networks
- Recommended areas - ways to explore users' future interests
- FFT learning notes (I think it is detailed)
- ADS-NPU芯片架构设计的五大挑战
- Crawler request module
- Leetcode 208. Implement trie (prefix tree)
- Leetcode sword finger offer 59 - ii Maximum value of queue
- PHP error what is an error?
- 关于softmax函数的见解
- Recursive method converts ordered array into binary search tree
猜你喜欢
Electrical data | IEEE118 (including wind and solar energy)
c#网页打开winform exe
激动人心,2022开放原子全球开源峰会报名火热开启
Loop structure of program (for loop)
Pbootcms plug-in automatically collects fake original free plug-ins
黄金价格走势k线图如何看?
Unity | 实现面部驱动的两种方式
Test de vulnérabilité de téléchargement de fichiers basé sur dvwa
Recoverable fuse characteristic test
Convert binary search tree into cumulative tree (reverse middle order traversal)
随机推荐
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
Finding the nearest common ancestor of binary search tree by recursion
Superfluid_ HQ hacked analysis
Development trend of Ali Taobao fine sorting model
MATLB|实时机会约束决策及其在电力系统中的应用
Questions about database: (5) query the barcode, location and reader number of each book in the inventory table
Overview of Zhuhai purification laboratory construction details
Hundreds of lines of code to implement a JSON parser
MATLB | real time opportunity constrained decision making and its application in power system
282. Stone consolidation (interval DP)
What is the most suitable book for programmers to engage in open source?
Leetcode study - day 35
SSH login is stuck and disconnected
有谁知道 达梦数据库表的列的数据类型 精度怎么修改呀
False breakthroughs in the trend of London Silver
Hcip---ipv6 experiment
BiShe - College Student Association Management System Based on SSM
Mobilenet series (5): use pytorch to build mobilenetv3 and learn and train based on migration
Finding the nearest common ancestor of binary tree by recursion
Crawler request module