In China, Dubbo has become the preferred RPC framework for many Internet companies in highly concurrent distributed scenarios. Dubbo has gone through a lot of processes from open source till now, from open source to suspension of maintenance in the middle. After three years of silence, Alibaba announced the restart of Dubbo project in September 2017. By February 2018, Ali had donated Dubbo to the Apache Foundation, and dubbo was incubated to become a top-level project at Apache.

Of course, the focus of this article is not on the use of Dubbo, but on how to use the Smart-Doc tool to generate documentation for dubbo’s RPC internal interface. Smart-doc is favored by many developers in China because of its concept of automatic derivation based on annotations and Java interface definitions. At the beginning of open source, Smart-Doc only supported restful API documentation. However, in the process of development, developers repeatedly asked smart-Doc if it could support dubbo RPC interface documentation. In smart-Doc 1.8.7, we’ve added support for the Dubbo RPC interface. Let’s see what’s in action.

1. Smart-doc integration

Smart-doc develops Maven plug-ins and Gradle plug-ins based on the principle of simplicity of use to reduce the integration difficulty of Smart-Doc and remove the dependency intrusion. You can choose the relevant plug-in based on the dependency build management tool you use. The following uses smart-doc-Maven-plugin to integrate Smart-doc to generate Dubbo as an example. Of course you can integrate smart-Doc to generate dubbo RPC interface documents in two ways:

• Use smart-Doc to scan dubbo API modules
• Use smart-doc to scan the Dubbo Provider module

Let’s look at the integration.

1.1 Adding plug-ins

Add smart-doc-Maven-plugin to your Dubbo API or dubbo Provider module. Of course, you just need to pick one of them

<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>[Latest version]</version> < Configuration > <! - specifies generating documentation using the configuration file, in the configuration file on their own projects - > < configFile >. / SRC/main/resources/smart - doc. Json < / configFile > <! -- specify projectName --> <projectName> test </projectName> <! -- Smart-Doc does not allow you to automatically analyze the source code from the other side of the family, or excludes the poor family from the other side. -- Format: groupId:artifactId; Refer to the following --> <! * --> <exclude>com.alibaba:fastjson</exclude> </excludes> <! Since version 1.0.8, the plugin provides includes support --> <! Smart-doc can automatically analyze the dependency tree and load all the dependent source code. In principle, this will affect the efficiency of the document construction. Therefore, you can use the plug-in to load your configured components. -- Format: groupId:artifactId; <include>com.alibaba:fastjson</include> </includes> </configuration> <executions> <! -- If you don't need to start smart-doc at compile time, <phase>compile</phase> <goals> HTML </goal> </execution> </executions> </plugin>Copy the code

Add the configuration file required by smart-doc

Add smart-doc.json configuration files to your Dubbo API or dubbo Provider module Reources

{
  "isStrict": false, // Whether to enable strict mode"allInOne": true, // Whether to merge documents into a filetrue
  "outPath": "D://md2"// Specify the output path of the document"projectName": "smart-doc"// Configure your own project name"rpcApiDependencies":[{// project open dubbo API interface module dependencies, configuration output to the document for user integration"artifactId":"SpringBoot2-Dubbo-Api"."groupId":"com.demo"."version":"1.0.0"}]."rpcConsumerConfig":"src/main/resources/consumer-example.conf"// Add the Dubbo Consumer integration configuration to the document so that the integrator can quickly integrate}Copy the code

For more detailed documentation on smart-doc, please refer to the official Project Wiki documentation

RpcConsumerConfig:

If you want to make dubbo consumer integration faster, you can put the integration configuration sample consumer-example.conf, which smart-doc will print directly to the document.

dubbo:
  registry:
    protocol: zookeeper
    address:  ${zookeeper.adrress}
    id: my-registry
  scan:
    base-packages: com.iflytek.demo.dubbo
  application:
    name: dubbo-consumer
Copy the code

Dubbo interface scanning

As mentioned above, Smart-Doc supports separate scans of the Dubbo API or Dubbo Provider. The scanning principle is mainly through the recognition of @dubbo annotation tag(idea can support adding custom annotation tag hint can refer to smart-Doc Wiki documentation) or dubbo @service annotation.

Scanning dubbo API

The Dubbo API is usually a very concise definition of the Dubbo interface. If you want smart-Doc to scan the Dubbo interface, add the @dubbo annotation tag. The following is an example:

* @author yu 2019/4/22. * @author Zhangsan 2019/4/22. * @version 1.0.0 * @dubbo */ public Interface UserService {/** * query all users ** @return*/ List<User> listOfUser(); /** * query ** @param userId * @ based on userIdreturn
     */
    User getById(String userId);
}
Copy the code

Scanning dubbo provider

If you want to generate RPC interface documents using the Dubbo Provider, you don’t need to add any additional annotation tags, smart-Doc automatically scans the @service annotation to do so.

/**
 * @author yu 2019/4/22.
 */
@Service
public class UserServiceImpl implements UserService {

    private static Map<String,User> userMap = new HashMap<>();

    static {
        userMap.put("1",new User()
                .setUid(UUIDUtil.getUuid32())
                .setName("zhangsan")
                .setAddress("Chengdu, Sichuan province")); } /** * get user * @param userId * @return
     */
    @Override
    public User getById(String userId) {
        returnuserMap.get(userId); } /** * get user * @return
     */
    @Override
    public List<User> listOfUser() {
        returnuserMap.values().stream().collect(Collectors.toList()); }}Copy the code

To generate

You can run the document generation command for the plug-in directly from the Maven command or click the plug-in visual command in IDEA.

Dubo-api documentation generates renderings

Add dependency

< the dependency > < groupId > com. Demo < / groupId > < artifactId > SpringBoot2 Dubbo - Api < / artifactId > < version > 1.0.0 < / version > </dependency> <dependency> <groupId>com.demo</groupId> <artifactId>SpringBoot2-Dubbo-Api</artifactId> The < version > 1.0.0 < / version > < / dependency >Copy the code

The user action

URI: dubbo://localhost:20880/com.iflytek.demo.dubbo.api.interfaces.UserService

Service: com.iflytek.demo.dubbo.api.interfaces.UserService

Protocol: dubbo

Author: yu 2019/4/22., zhangsan 2019/4/22.

Version: 1.0.0

Querying All Users

Definition: the List listOfUser ()

Description: Queries all users

Response-fields:

Query by user ID

Definition： User getById(String userId)

Description: Query by user ID

Invoke-parameters:

Response-fields:

Used to summarize

Smart-doc support for Dubbo RPC document generation is relatively late, and there are no better tools and templates on the market. This section of the Dubbo RPC document needs more users to make issues and improvements. Of course if you agree and like smart-Doc please go to the project and give us some support for Little Star.

Yards cloud address

Making the address