{"id":13525244,"url":"https://github.com/YeDaxia/JApiDocs","last_synced_at":"2025-04-01T04:31:34.561Z","repository":{"id":37742936,"uuid":"79034430","full_name":"YeDaxia/JApiDocs","owner":"YeDaxia","description":"A magical api documentation generator without annotation for springboot. [No Time Maintain]","archived":false,"fork":false,"pushed_at":"2022-10-13T08:59:20.000Z","size":8066,"stargazers_count":1696,"open_issues_count":39,"forks_count":330,"subscribers_count":57,"default_branch":"master","last_synced_at":"2025-03-31T01:11:06.425Z","etag":null,"topics":["api","api-documentation","apidocs","springboot"],"latest_commit_sha":null,"homepage":"https://japidocs.agilestudio.cn/","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YeDaxia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-15T13:30:17.000Z","updated_at":"2025-03-27T02:21:06.000Z","dependencies_parsed_at":"2022-08-08T21:30:55.314Z","dependency_job_id":null,"html_url":"https://github.com/YeDaxia/JApiDocs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YeDaxia%2FJApiDocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YeDaxia%2FJApiDocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YeDaxia%2FJApiDocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YeDaxia%2FJApiDocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YeDaxia","download_url":"https://codeload.github.com/YeDaxia/JApiDocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246586087,"owners_count":20801025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-documentation","apidocs","springboot"],"created_at":"2024-08-01T06:01:17.095Z","updated_at":"2025-04-01T04:31:34.541Z","avatar_url":"https://github.com/YeDaxia.png","language":"Java","funding_links":[],"categories":["开源","Java"],"sub_categories":[],"readme":"# Getting Started\n\nSupported JDK：1.8+\n\n## Quick Start\n\n### Step One：Add Dependency\n\nmaven:\n\n```\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.yedaxia\u003c/groupId\u003e\n  \u003cartifactId\u003ejapidocs\u003c/artifactId\u003e\n  \u003cversion\u003e1.4.4\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\ngradle:\n\n```\ncompile 'io.github.yedaxia:japidocs:1.4.4'\n```\n\n### Step Two：Configuration\n\nYou can run code below at any main():\n\n```java\nDocsConfig config = new DocsConfig();\nconfig.setProjectPath(\"your springboot project path\"); // root project path \nconfig.setProjectName(\"ProjectName\"); // project name\nconfig.setApiVersion(\"V1.0\");       // api version\nconfig.setDocsPath(\"your api docs path\"); // api docs target path\nconfig.setAutoGenerate(Boolean.TRUE);  // auto generate \nDocs.buildHtmlDocs(config); // execute to generate \n```\nIf there is no accident, after executing the above code, you can see the generated documents in the configured directory.\n\n## Code Style Requirements\n\nJApiDocs is implemented by parsing Java source code. To make JApiDocs work correctly, you need to follow certain coding standards in the writing of `Controller` in the project.\n\nYou can refer the `SpringDemo` module in the source code for comparison and understanding.\n\n### 1. Add Necessary Code Comments\n\nThe class comment will correspond to the first-level grouping. You can also specify the group name through `@description`; JApiDocs will use `@param` to find parameters for further analyze.\n\n```java\n/**\n * User API\n */\n@RequestMapping(\"/api/user/\")\n@RestController\npublic class UserController {\n\n\n    /**\n     * Get User List\n     * @param listForm\n     */\n    @RequestMapping(path = \"list\", method = {RequestMethod.GET,  RequestMethod.POST}  )\n    public ApiResult\u003cPageResult\u003cUserVO\u003e\u003e list(UserListForm listForm){\n        return null;\n    }\n\n    /**\n     * Save User\n     * @param userForm\n     */\n    @PostMapping(path = \"save\")\n    public ApiResult\u003cUserVO\u003e saveUser(@RequestBody UserForm userForm){\n        return null;\n    }\n\n    /**\n     * Delete User\n     * @param userId user id\n     */\n    @PostMapping(\"delete\")\n    public ApiResult deleteUser(@RequestParam Long userId){\n        return null;\n    }\n}\n```\n\nIf the submitted form is `application/x-www-form-urlencoded` type, you can add a description after `@param` or add an comment in JavaBean object :\n\n```java\n// in @param\n@param userId user id\n```\n\n```java\n// at FormBean\npublic class UserListForm extends PageForm{\n    private Integer status; //user status\n    private String name; //user name\n}\n```\n\nThis form type would show as table in the document：\n\nparameter name|parameter type|must|description\n--|--|--|--\nstatus|int|N|user status\nname|string|N|user name\n\nIf the submitted form is `application/json` type, corresponding to the `@RequestBody` annotation in SpringBoot, it will display as `json` format in the document:\n\n```java\n{\n  \"id\": \"long //user id\",\n  \"name\": \"string //user name\",\n  \"phone\": \"long // user phone\",\n  \"avatar\": \"string // user avatar url\",\n  \"gender\": \"byte //use gender\"\n}\n```\n\n### 2. Return Specific Class Type\n\nWe know that if a Controller Class declares @RestController, SpringBoot will return json data to the front end. JApiDocs also uses this feature to parse the result in the api method, but since JApiDocs parses the source code statically, you must clearly return a specific class type. JApiDocs supports complex class analysis such as inheritance, generics, and loop nesting.\n\nSuch as `saveUser` ：\n\n```java\n /**\n * save user\n * @param userForm\n */\n@PostMapping(path = \"save\")\npublic ApiResult\u003cUserVO\u003e saveUser(@RequestBody UserForm userForm){\n    return null;\n}\n```\n\n`ApiResult\u003cUserVO\u003e` shows the data structure of response，after processing by JApiDocs，it's like this：\n\n```json\n{\n  \"code\": \"int\",\n  \"errMsg\": \"string\",\n  \"data\": {\n    \"userId\": \"string //user id\",\n    \"userName\": \"string //user name\",\n    \"friends\": [\n      {\n        \"userId\": \"string //user id\",\n        \"userName\": \"string //user name\"\n      }\n    ],\n    \"readBooks\": [\n      {\n        \"bookId\": \"long //book id\",\n        \"bookName\": \"string //book name\"\n      }\n    ],\n    \"isFollow\": \"boolean //is follow\"\n  }\n}\n```\n\nIf you don't like the *return* type, you can also use `@ApiDoc` in JApiDoc to declare the response type，you can refer the `@ApiDoc` chapter below.\n\n### 3. Api Java Beans Should In Source Code \n\nWe know that there is no comment information in the compiled class bytecode. For JApiDcos to work better, \nyour Form bean Class and return Class should be in the source code, otherwise the generated document will be missing description information.\nAnyway, in version 1.4.2, JApiDocs will try to parse the field information by reflection when can't find the source code (the dependent class is in the jar package).\n\n# Advanced Configuration\n\n## @ApiDoc\n\nBy default, JApiDocs only exports the api that declares `@ApiDoc`. We previously removed this restriction by setting `config.setAutoGenerate(Boolean.TRUE)`.\n\nIf you don't want to export all apis, you can turn off the `autoGenerate` and add `@ApiDoc` to the `Controller` class or api method to determine which api need to be exported.\n\nLet's see how the `@ApiDoc` works on api method:\n\n- result: the returned object type, it will override the returned object of SpringBoot\n- url: request url，extended field, used to support non-SpringBoot projects\n- method: request method，extended field, used to support non-SpringBoot projects\n\nex：\n\n```java\n@ApiDoc(result = AdminVO.class, url = \"/api/v1/admin/login2\", method = \"post\")\n```\n\n## @Ignore\n\n### Ignore Controller Class\n\nAdd `@Ignore` at Controller, all of its method would ignore.\n\n```java\n\n@Ignore\npublic class UserController { \n \n}\n```\n\n### Ignore Method\n\n```java\n\n@Ignore\n@PostMapping(\"save\")\npublic ApiResult saveUser(){\n  return null;\n}\n\n```\n\n### Ignore Field\n\nIf you don’t want to export a field in the object, you can add `@Ignore` annotation to this field, so that JApiDocs will automatically ignore it when exporting the document:\n\nex:\n \n ```java\npublic class UserForm{\n    @Ignore\n    private Byte gender;\n}\n```\n\n## Export More Format\n\n### Export Markdown\n\n```java\nconfig.addPlugin(new MarkdownDocPlugin());\n```\n\n### Export Pdf Or Word\n\nYou can use [pandoc](https://pandoc.org/) convert markdown to pdf or word.\n\n## Custom Code Templates\n\nIn addition to supporting api document export, JApiDocs currently also supports the generation of return object codes for Android and iOS, corresponding to Java and Object-C languages,\nIf you want to modify the code template, you can use the following steps:\n\n### Step One：Modify Code Templates\n\nCopy the code templates in the `library` project `resources` directory of the source code, where `IOS_` means Object-C code template, and `JAVA_` starts with Java code,\nThe symbol similar to \"${CLASS_NAME}\" in the template is a substitution variable. You will understand the meaning compare to the generated code, and try to modify it according to the code template you want.\n\n### Step Two：Use The New Code Templates\n\nUse `DocsConfig` to replace with new template:\n\n```java\ndocsConfig.setResourcePath(\"your new tempalte path\");\n```\n\n## More Custom Features\n\nJApiDocs provides a plug-in interface. You can implement more rich features through the plug-in interface. \nThe following describes how to make this:\n\n### Step One：Implements *IPluginSupport* Interface\n\n```java\npublic class CustomPlugin implements IPluginSupport{\n    \n    @Override\n    public void execute(List\u003cControllerNode\u003e controllerNodeList){\n        // do something you want\n    }\n}\n```\n\n### Step Two：Add Your Plugin\n\n```java\n config.addPlugin(new CustomPlugin());\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYeDaxia%2FJApiDocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYeDaxia%2FJApiDocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYeDaxia%2FJApiDocs/lists"}