When there is a need for interface docking, development finally no longer has to worry about the difficulty of writing API documents, and there is no need to rewrite interface documents one by one! Install this IDEA plug-in to import documents into Postcat in one step.

This plug-in is simple to operate, easy to use, and can
Let the developer save
APIs
The job of document writing is more focused on development.The plug-in analyzes user comments for interface analysis, and finally generates interface documents and uploads them to the Postcat server, enabling developers to manage and share APIs on Postcat, improving collaboration capabilities and development speed.

What is the difference with Swagger?

The Postcat plugin will not invade the code, and there is no need to add any jar package dependencies

The plug-in analyzes user comments for interface analysis, and finally generates interface documents and uploads them to the Postcat server, enabling developers to manage and share APIs on Postcat, improving collaboration capabilities and development speed.

Postcat provides a variety of extended comments,like
@path,
@url,
@method,
@name,
@hiddenand
@requiredthese annotations can be customized or compatible with existing annotations in the settings interface.

also,
Postcat also provides a comment generation function, for classes and methods with no or only a few annotations, developers do not need to manually add them. This function can analyze the meaning of method fields and automatically generate annotations. Developers only need to check or fine-tune according to actual scenarios to generate a relatively complete API document.

If the original comment is insufficient, Postcat will supplement the comment by adding, when removing comments, only those extended comments provided by Postcat will be removed, and the user’s own comments will not be destroyed. At the same time, developers can also use the “intent” function to locally generate plug-in comments, and make adjustments and modifications.

Postcat provides a variety of
APIs
The upload method is convenient for developers to use in different scenarios:

• For existing projects using Postcat for the first time, developers can use the
  Toolsunder the group
  Upload Project Api DocTo complete the project-level interface upload.

• For the Controller created under the new requirement, after completing the interface definition, the developer can right-click the menu and select
  Upload All Api To upload all files at a single file level, so that there are documents first and then logic, and the front-end and back-end work will no longer be blocked serially.

• For the modification of a certain part of a single interface, there is no need to upload all of them. Developers can right-click the menu and select
  Upload ApiFunction, this function will display the interface information of the current editing class, and provide an interface preview and interface selection interface, so that users can check and upload the target API that needs to be updated or uploaded.

How to install and configure?

IDEA version needs to be greater than IntelliJ IDEA 2022.03

1. Fill in the configuration information

The configuration information needs to be filled in for the first upload, and the configuration information items are independent.

1. Server is filled in by default: https://postcat.com/api, users do not need to modify

2. Token acquisition

3. 

   3. Get WorkspaceID and ProjectID

1. 

   4. StringType determines the string type of the input and output parameters. Only when the parameter name conforms to the hump specification at the beginning will the change be found. The preview window can see the result of the change

1. When the parameter named
userInfochoose camelCase, it is still
userInfowhich is the default option

2. When the parameter name is
userInfoselect lower_underscore, will become
user_info

3. When the parameter name is
userInfoselect UPPER_UNDERSCORE, it will become
USER_INFO

2. Precautions

1. Before parsing and uploading, please ensure that IDEA has been built in the project and related dependencies have been downloaded.

2. It is strongly recommended to use the comments defined by the plug-in. The plug-in has a powerful function of generating comments. It is strongly recommended to generate the comments of the plug-in before editing and uploading. The comments can also be customized in the settings.

3. When plugin annotations are not recognized, only for
   Spring MVC,
   Swagger.v2and
   Swagger(OpenAPI).v3The annotations only do some simple support. To avoid missing required parameters, it is recommended to use plugin annotations.

4. The generate annotations feature will
   Spring MVC,
   Swagger.v2 and
   Swagger(OpenAPI).v3The annotations only do some simple support, and don’t let you rewrite it.

5. HTTPThe interface judges only through routing and request methods to perform overlay update processing

6. For the API that has been uploaded, it has been manually modified on the web. It is not recommended to use the upload function, because the plug-in upload will overwrite the previous content.

7. After generating/hand typing the plug-in javadoc, the interface uri, request method (GET/POST), etc. have been modified, and the plug-in javadoc needs to be manually modified, otherwise the plug-in will still recognize the old plug-in javadoc information.

8. Auto-generated class annotations are uploaded by default to
   默认分组please fill in the real group by yourself, and the group is identified by name.

   1. For multi-level grouping, use
      .Separated, for example, the interface needs to be passed to
      第三方under the group
      用户For grouping, the group-name should be filled with third-party.user.

9. @group-nameComments are supported at the method level and are not generated by default. You can manually add them to method comments, and the plug-in will help you save the current method into the corresponding group.

10. project level api scan and upload, top menu
    [Tools -> Upload Project Api Doc]see the specific usage rules
    项目级上传.

11. Generated class annotations are not generated by default
    @requirednote, only for
    javax.validation.constraints.NotNullAnnotated fields are generated.

12. not recommended
    @remarkComments, the plug-in retains the recognition function and splices the content into the field description, and the generated class comments will not be automatically generated.

13. pass
    @PathVariablethe POST method recognizes the parameter as the Formdata type by default, and the GET method recognizes the parameter as the query type by default.

14. //The marked annotation cannot be recognized, please use
    /** */logo.

https://gitee.com/eolink_admin/postcat