Key Knowledge Summary

We tend to generate API documentation using Swagger (check out this tutorial by one of my favorite authors), which is a bit intrusive, and you need to mark annotations on variables, which is a lot of extra work. Instead of annotating manually, it would be nice to be able to generate documents from comments in javadoc format that we normally write, just like the Javadoc instructions do, and even better to allow custom output formats.

This allows you to document the API while writing the comments

About the javadoc

First, Javadoc is a tool built into the JDK to extract comments from source code and generate documentation.

Doclet parameters

Then we look at the argument to the Javadoc command -doclet. The class name that follows this parameter allows you to put the output of your custom Javadoc into this class to get the RootDoc object.

Use custom Doclets

When we use com. Sun. View javadoc. Main. The execute javdoc instruction will read – after the doclet class name, here is the full name, limited JavaDocLetUtil Public static Boolean start(RootDoc RootDoc) public static Boolean start(RootDoc RootDoc)

public class JavaDocLetUtil {
    private static RootDoc rootDoc;
    private JavaDocLetUtil(a){}
    public static boolean start(RootDoc rootDoc){
        JavaDocLetUtil.rootDoc = rootDoc;
        return true;
    }

    private static void execute(String[] args){
        com.sun.tools.javadoc.Main.execute(args);
    }

    private static RootDoc getRootDoc(a){
        return Optional.ofNullable(rootDoc).orElseThrow(()->new RuntimeException("Uninitialized"));
    }

    public static RootDoc generateControllersRootDoc(String controllerPagePath){
        List<String> args = new ArrayList<>();
        args.add("-doclet");
        args.add(JavaDocLetUtil.class.getName());
        final ArrayList<String> filePath = new ArrayList<>();
        // omit the step of adding the filePath to filePath
        args.addAll(filePath);
        execute(args.toArray(new String[args.size()]));
        returnJavaDocLetUtil.getRootDoc(); }}Copy the code

This code executes the logic as

JavaDocLetUtil. GenerateControllersRootDoc () the incoming documents address Splicing instruction to execute after implementation, and finally getRootDoc () to obtain the RootDoc objectCopy the code

About RootDoc objects

Here would involve so few object RootDoc, ClassDoc, MethodDoc

The relationship is RootDoc contains ClassDoc(depending on how many classfile addresses you pass in) and ClassDoc contains MethodDoc (depending on how many methods the class has)

The schematic diagram is as follows

About the ClassDoc interface

The inheritance is as follows

We focus on a few key approaches

1, MethodDoc [] the methods ()

We know from the method signature that this method is used to return all MethodDoc objects in that class

2, String qualifiedName() (inherited from ProgramElementDoc interface)

It is used to return the full name, so we can get the corresponding Class object through class.forname (classdoc.qualifiedName ())

3, String commentText ();

The Tag [] tags ();

String commentText(); (Inherited from the Doc interface)

To return the contents of our comments, this is the key to achieving both non-intrusive and informative descriptions

About the MethodDoc interface

The inheritance is as follows

We focus on a few key approaches

1, the String name (); (Derived from the Doc class)

Public void fun(){} public void fun(){}

2, the Parameter [] the parameters (); (Inherited from ExecutableMemberDoc)

Returns the Parameter of the fully qualified called com. Sun. Javadoc. Paramter, this method is used to get Parameter information

QualifiedTypeName () : String qualifiedTypeName() : com.sun.javadoc.type); Then use Class. ForName to get the corresponding Class object

GetMethod () : getMethod (); getMethod () : getMethod (); getMethod () : getMethod ()

3, the Tag [] tags ()

​ Tag[] tags(String tagname)

String commentText() (inherited from the Doc interface)

The String text() in the Tag class returns the comment information for the Tag

For example

If Tag = @param list delete ID set,text = @param list delete ID set

conclusion

Typically a module is a Controller Class, described by the Class annotation, and the corresponding Class object is used to get annotations such as @requestMapping to get the path

RequestMapping (@requestMapping) (@responseBody) (@responseBody) (@responseBody) (@responseBody) (@responseBody) The @requestheader annotation in turn adds additional description to the parameters