Bye, swagger! Use smart doc to generate interface documents without intrusion

Time:2022-5-20

What is smart doc?

The API of apache-collection and mark-2 can generate comments for you at the same time, and the API of apache-doc-collection and mark-2 can generate comments for you at the same time 0 +, OpenAPI 3.0 +.

How to use smart doc?

1、Add Maven Plugin
<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.2.4.1</version>
    <configuration>
        <!-- Specify the configuration file used to generate the document. The configuration file is placed in your own project -- >
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!-- Specify project name -- >
        < ProjectName > test < / ProjectName >
        <!-- Smart doc can automatically analyze the dependency tree and load the source code of third-party dependencies. If some framework dependency libraries cannot be loaded, resulting in an error, please use excludes to exclude -- >
        <excludes>
            <!-- The format is: groupid: artifactid; Refer to the following -- >
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!-- Since version 1.0.8, the plug-in provides includes support. After configuring includes, the plug-in will be loaded according to the user's configuration rather than automatically. Therefore, pay attention to -- > when using it
        <!-- Smart doc can automatically analyze the dependency tree and load all dependent source code, which will affect the efficiency of document construction in principle. Therefore, you can use includes to let the plug-in load your configured components -- >
        <includes>
            <!-- The format is: groupid: artifactid; Refer to the following -- >
            <!-- Regular expressions can also be supported, such as: com alibaba:.* -->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
      <execution>
        <goals>
            <!-- Smart doc provides HTML, OpenAPI, markdown and other goals, which can be configured on demand -- >
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
  </plugin>
2. Add smart doc. In the project directory JSON configuration file. Common configurations are as follows
{
  "serverUrl": " http://localhost:8080 ", // server address, not required. It is recommended to set it to http: // {{server}} when exporting postman. It is convenient to directly set environment variables in postman
  "AllInOne": true, // whether to merge the document into one file. Generally, it is recommended to be true
  "Outpath": "Src / main / resources / static / Doc", // specify the output path of the document
  "Coverold": true, // whether to overwrite the old file. It is mainly used to overwrite mardown files
  "Createdebugpage": true, // @ since 2.0.0 smart doc supports creating HTML pages that can be tested. It only works in AllInOne mode.
  "ProjectName": "smart Doc", // configure your own project name
  "Sortbytitle": false, // interface Title sorting, default to false, @ since version 1.8.7
  "Showauthor": true, // whether to display the interface author name. The default is true. If you don't want to display it, you can close it
  "Allinonedocfilename": "index. HTML" // customize the output document name, @ since 1.9.0
}
3. Add standard Java annotations to the corresponding interface and entity classes
/**
   *Get user ID
   * @param id
   * @return
   */
  @GetMapping("user/{id}")
  public R<User> getUser(@PathVariable Integer id){
      User user = new User();
      user.setId(id);
      user. Setusername ("Wang Dafu");
      return R.ok(user);
  }
4. Use Maven plug-in to generate interface documents

1.1 in idea, you can directly generate corresponding documents through plugins and smart doc plug-ins in Maven helper

Bye, swagger! Use smart doc to generate interface documents without intrusion

1.2 Maven command mode

//Generate HTML
mvn -Dfile.encoding=UTF-8 smart-doc:html
//Generate ADOC
mvn -Dfile.encoding=UTF-8 smart-doc:adoc

Smart doc effect example

Bye, swagger! Use smart doc to generate interface documents without intrusion

HTML global presentation
Bye, swagger! Use smart doc to generate interface documents without intrusion

Request parameter example
Bye, swagger! Use smart doc to generate interface documents without intrusion

Request response example

Open source address:https://gitee.com/smart-doc-team/smart-doc

Recommended Today

JS generate guid method

JS generate guid method https://blog.csdn.net/Alive_tree/article/details/87942348 Globally unique identification(GUID) is an algorithm generatedBinaryCount Reg128 bitsNumber ofidentifier , GUID is mainly used in networks or systems with multiple nodes and computers. Ideally, any computational geometry computer cluster will not generate two identical guids, and the total number of guids is2^128In theory, it is difficult to make two […]