Small knowledge, big challenge! This paper is participating in theEssentials for programmers”Creative activities.
preface
Backend developers know how painful it is to write an API doc, but the number of interfaces, especially in the early stages of a project, hundreds of interfaces, is really tiring, so you have to use some framework that automatically builds doc
Swragger was the first choice, but it was too intrusive, so smart-Doc, the main character of this article, could only be built as a simple version, but the general project documentation would suffice
The website address
Gitee.com/smart-doc-t…
Based on using
There are basically two ways to use it
- Maven plug-in integration allows you to generate up-to-date documentation directly when building a project
- Program ahead of time
I’m currently using the second one, because the first one has some problems supporting multiple maven projects and has not been successful (there is a solution on the website), and the second one also generates postman interface and debugging is very fun
Specific steps are written on the official website, I just post my configuration
Generate in single HTML form
/** * this includes setting the request header to use the defined comment */ for missing annotation fields in bulk during document generation
@Test
public void testBuilderControllersApi(a) {
ApiConfig config = new ApiConfig();
// config.setServerUrl("http://localhost:9002");
//true strictly requires comments and is recommended
config.setStrict(false);
//true exports the document merge to a markdown
config.setAllInOne(true);
// Generate HTML to encrypt the document name without exposing the controller name
config.setMd5EncryptedHtmlName(true);
// Specify the document output path
// since version 1.7, choose to generate static HTML doc documents using the path: DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath("src/main/resources/static/doc_3");
// @since 1.2, if this option is not configured, all controllers will be matched by default,
// If multiple controllers need to be configured, separate them with commas
config.setPackageFilters("com.eco.newpc.controller");
The default loading code for the SourcePaths is under project SRC /main/ Java, and can be loaded together if some of the project's entities come from outside
config.setSourceCodePaths(
Since version 1.7.0, it is possible to add an external code path without setting the local code path
// sourcecodepath.path ().setdesc (" this project code ").setPath(" SRC /main/ Java "),
new SourceCodePath().setDesc("Load out-of-project code").setPath("/Users/hans/work_space/java_project/eco-pc-fanli/pc-common/src/main/java"),
new SourceCodePath().setDesc("Load out-of-project code").setPath("src/main/java"));/ / since 1.7.5
// If this option is false, the version number is automatically added to the name of the allinone.md file generated by smart-doc
config.setCoverOld(true);
/ / since 1.7.5
// Set the item name (optional). If you do not set the item name, it will cause the number to be displayed incorrectly using some tools that automatically add the title number
config.setProjectName("System");
// Set the request header
config.setRequestHeaders(
ApiReqHeader.header().setName(HttpHeaders.AUTHORIZATION).setType("string").setDesc("Basic auth credentials"));// For external JAR classes, the comments will be erased after compilation. You can't get the comments, but please use setSourcePaths to load the external code if you have a lot of them
// If this is the case, add the field and comment yourself. Api-doc will comment the field if it encounters the same field
config.setResponseBodyAdvice(BodyAdvice.builder().setClassName(ServerResponse.class.getName()).setDataField("data"));
config.setDataDictionaries(
ApiDataDictionary.builder().setEnumClass(LogTypeEnum.class).setTitle("Log Type").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OpTypeEnum.class).setTitle("Operation type").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderBindTypeEnum.class).setTitle("Order binding Type").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderStatusEnum.class).setTitle("Order Type").setCodeField("code").setDescField("desc"));long start = System.currentTimeMillis();
HtmlApiDocBuilder.buildApiDoc(config);
// since version 1.7+, smart-doc supports the creation of HTML documents with bookmarks. HTML documents can be selected under denomination
//HtmlApiDocBuilder.builderControllersApi(config);
// since version 1.7+, smart-doc supports generating AsciiDoc documents. You can convert AsciiDoc into HTML5 format.
//@see https://gitee.com/sunyurepository/api-doc-test
//AdocDocBuilder.builderControllersApi(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
Copy the code
This can be accessed directly in the browser because it is in the static folder of the project
Generate the postman
@Test
public void toPostMan(a) {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://{{simple-9002}}/ant");
//true strictly requires comments and is recommended
config.setStrict(false);
//true exports the document merge to a markdown
config.setAllInOne(true);
// Generate HTML to encrypt the document name without exposing the controller name
config.setMd5EncryptedHtmlName(true);
// Specify the document output path
// since version 1.7, choose to generate static HTML doc documents using the path: DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath("src/main/resources/static/postman");
// @since 1.2, if this option is not configured, all controllers will be matched by default,
// If multiple controllers need to be configured, separate them with commas
config.setPackageFilters("com.eco.newpc.controller");
The default loading code for the SourcePaths is under project SRC /main/ Java, and can be loaded together if some of the project's entities come from outside
config.setSourceCodePaths(
Since version 1.7.0, it is possible to add an external code path without setting the local code path
// sourcecodepath.path ().setdesc (" this project code ").setPath(" SRC /main/ Java "),
new SourceCodePath().setDesc("Load out-of-project code").setPath("/Users/hans/work_space/java_project/eco-pc-fanli/pc-common/src/main/java"),
new SourceCodePath().setDesc("Load out-of-project code").setPath("src/main/java"));/ / since 1.7.5
// If this option is false, the version number is automatically added to the name of the allinone.md file generated by smart-doc
config.setCoverOld(true);
/ / since 1.7.5
// Set the item name (optional). If you do not set the item name, it will cause the number to be displayed incorrectly using some tools that automatically add the title number
config.setProjectName("System");
// Set the request header
config.setRequestHeaders(
ApiReqHeader.header().setName(HttpHeaders.AUTHORIZATION).setType("string").setDesc("Basic auth credentials").setValue("{{PC-Token}}").setRequired(true));// For external JAR classes, the comments will be erased after compilation. You can't get the comments, but please use setSourcePaths to load the external code if you have a lot of them
// If this is the case, add the field and comment yourself. Api-doc will comment the field if it encounters the same field
config.setResponseBodyAdvice(BodyAdvice.builder().setClassName(ServerResponse.class.getName()).setDataField("data"));
long start = System.currentTimeMillis();
PostmanJsonBuilder.buildPostmanCollection(config);
config.setDataDictionaries(
ApiDataDictionary.builder().setEnumClass(LogTypeEnum.class).setTitle("Log Type").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OpTypeEnum.class).setTitle("Operation type").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderBindTypeEnum.class).setTitle("Order binding Type").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderStatusEnum.class).setTitle("Order Type").setCodeField("code").setDescField("desc"));// since version 1.7+, smart-doc supports the creation of HTML documents with bookmarks. HTML documents can be selected under denomination
//HtmlApiDocBuilder.builderControllersApi(config);
// since version 1.7+, smart-doc supports generating AsciiDoc documents. You can convert AsciiDoc into HTML5 format.
//@see https://gitee.com/sunyurepository/api-doc-test
//AdocDocBuilder.builderControllersApi(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
Copy the code
insufficient
Although comfortable, the enterprise level documentation is still lacking, and you may need to change the source code yourself
Let’s say I have a class property of type int, and there are three of them, 1-new, 2-old, 3-unknown, something like that, and then I have to annotate the property, which is a little bit of a hassle, so it’s better to recognize it directly