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