project

  • Github.com/liuhuagui/s… A RESTful API documentation tool based on Java standard annotations
  • Smalldoc – antd – react – UI (github.com/liuhuagui/s…

Why the wheel?

  • Obsessive-compulsive disorder patients, can not accept Swagger’s various annotations caused by the invasion of code miscellaneous, more eager to clean the code;
  • There is a learning cost to using annotations;
  • Then try using Apidoc. Although Apidoc is based on annotations to generate documents, the learning cost is not reduced. You need to learn additional annotation tags, and you have to use these special tags to manually write out the information about the interface you need.
  • There are also projects that generate documentation based on Java standard annotations, but some do not support entity parameters, generic variables, multi-module dependencies, and some have too many bugs, unfriendly UI, too complex to use, or even problems with logic processing.

features

  • Generate documents based on Java source code, standard annotations and Tag, no code intrusion, ensure clean code, and ensure developers’ annotation habits and specification
  • Provides a friendly default UI
  • Provides a documented RESTEful API to support the implementation of custom UIs
  • Provide standard configuration mode, more convenient to use
  • Spring-boot-starter supports both traditional Spring and spring-boot
  • Support for associated entity parameters
  • Supports generics
  • A parameter can be ignored
  • Data structures with specified packages or specified type parameters can be ignored to resolve
  • Support for multi-module projects (parsing source code or data structures from specified Jar packages)

implementation

  • Parsing the source code file, generating documentation information from the source code and its annotations. So far, the tags used in annotations are standard Tags for Java annotations. In the future, some necessary custom tags may be added, and there may even be a Tag extension mechanism that allows users to define their own tags and how they are handled.

  • When you think about generating Java RESTful API documents, you start by thinking about how Java API documents are generated, Javaparser » Javaparser-core or com.thoughtworks. qDOX » qDOX, But choose the JDK Javadoc Tool (docs.oracle.com/en/java/jav… Tool is the corresponding API Javadoc API (docs.oracle.com/en/java/jav…

  • Since the author is still using Java8, the implementation of the project is entirely based on the old Javadoc API

    • Package com. Sun. Tools. The javadoc (docs.oracle.com/en/java/jav…).
    • Package com. Sun. Javadoc (docs.oracle.com/en/java/jav…).

    Among them:

    Module jdk.javadoc Package com.sun.tools.javadoc This package and its contents are deprecated and may be removed in a future release. See javax.tools.ToolProvider.getSystemDocumentationTool and javax.tools.DocumentationTool for replacement functionality.

    Module jdk.javadoc Package com.sun.javadoc Note: The declarations in this package have been superseded by those in the package jdk.javadoc.doclet. For more information, see the Migration Guide in the documentation for that package.

    @Deprecated(since="9",forRemoval=true)
public class Main extends Object
Copy the code

    As you can see, the old Javadoc API has been deprecated since Java9 and will be removed in the near future, but thankfully it has not been removed until the latest major release of Java12, so users of Java12 and earlier versions can rest assured that new API support will be provided in the future.

  • Smalldoc-antd-react-ui smallDoc-antd-react-UI smallDoc-antd-react-UI smallDoc-antd-react-UI smallDoc-antd-react-UI smallDoc-antd-react-UI (github.com/liuhuagui/s…

use

The example is a spring-boot project, using application.yml as the configuration file

Introduction of depend on
<dependency>
    <groupId>com.github.liuhuagui</groupId>
    <artifactId>smalldoc-spring-boot-starter</artifactId>
    <version>2.3</version>
</dependency>
Copy the code
configuration

Interface documentation is usually used at development time, just make sure the documentation configuration works in the development environment — spring.profiles. Active =dev

server: 
  port: 8080
  servlet:
    context-path: /my-project
spring: 
  profiles:
    active: dev
---
spring:
  profiles: dev
smalldoc:
  source-paths: # additional source path (the project source path is already included by default, no need to add it)
    - 'D:\Workspaces\myBeanProject\my-bean\src\main\java'
    - 'D: \ Maven \ Repositories \ repository \ com \ aliyun \ aliyun - Java - SDK - core \ 3.5.0'
  packages:
    - quantity.knowledgebase
    - my.bean
    - com.aliyuncs.auth.sts
  project-name: My document
  enabled: true # Default is true
  url-pattern: /smalldoc/* /smalldoc/*
Copy the code
Access to the address
  • URL: http://192.168.1.76:8080/my-project/smalldoc/
  • METHOD: GET
Interface source code
/** * Create, edit, publish, customize articles *@author KaiKang [email protected]
 */
@RestController
@RequestMapping("w")
public class WriteArticleController {
    /** * Original articles save in edit *@paramThe content content *@paramOaCopy original article copy *@returnData - Draft ID *@author KaiKang [email protected]
     */
    @PostMapping(path = "o/save_draft",produces = {"text/plain"."application/json; charset=UTF-8"},consumes = "application/x-www-form-urlencoded")
    public Result<Long> saveOriginalDraft(String content, OriginalArticleCopy oaCopy, HttpServletRequest request) {
        return writeArticleService.saveOriginalDraft(content, oaCopy);
    }

    /** * This is just a test interface *@paramThe content content *@returnReturn data *@author KaiKang [email protected]
     */
    @GetMapping(path = "o/save",produces = {"text/plain"."application/json; charset=UTF-8"})
    public Result<OriginalArticle> save(String content, HttpServletRequest request) {
        return null; }}Copy the code
Interface documentation

Documentation API (for implementing custom UI)
  • URL: http://192.168.1.76:8080/my-project/smalldoc/
  • METHOD: POST

Pay attention to

  • source-pathsThe configuration item represents an additional source path. The source path of the project is already included by default. There is no need to add it, just specify the package to scan, for example:my.project.controller
  • The program will only resolve the class name*ControllerInterface information in the source code of
  • The program does not support The Linux environment. Before the project is packaged and deployed, remember to close the document function. There are various ways to close the document, such as:
    1. spring.profiles.active=*(*As long as it is not Dev), the development environment configuration is no longer activated
    2. smalldoc.enabled=false, disable enable
    3. Change the dependency scope totestAnd then we pack it, and we connect it like thissmalldocJar packages will not be packaged (recommended) 
       <dependency>
   	<groupId>com.github.liuhuagui</groupId>
   	<artifactId>smalldoc-spring-boot-starter</artifactId>
   	<version>2.3</version>
   	<scope>test</scope>
 </dependency>
Copy the code

community

If you need help with the process or want to add some features to your project, welcome issue — github.com/liuhuagui/s…