{"id":14983090,"url":"https://github.com/willing-xyz/restdoc","last_synced_at":"2025-10-29T21:30:39.124Z","repository":{"id":35940140,"uuid":"187767967","full_name":"Willing-Xyz/RestDoc","owner":"Willing-Xyz","description":"在运行时，使用Javadoc文档注释生成Swagger/OpenAPI规范","archived":false,"fork":false,"pushed_at":"2023-12-21T05:45:12.000Z","size":1888,"stargazers_count":66,"open_issues_count":6,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-02T04:41:34.883Z","etag":null,"topics":["javadoc","javadoc-swagger","spring","springboot","springfox","springmvc","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"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/Willing-Xyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-21T05:31:06.000Z","updated_at":"2024-11-13T09:40:25.000Z","dependencies_parsed_at":"2024-09-29T06:16:14.897Z","dependency_job_id":null,"html_url":"https://github.com/Willing-Xyz/RestDoc","commit_stats":{"total_commits":139,"total_committers":5,"mean_commits":27.8,"dds":"0.24460431654676262","last_synced_commit":"df2701719fbe1a5333b3410bd5f0bba02c7a37fa"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Willing-Xyz%2FRestDoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Willing-Xyz%2FRestDoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Willing-Xyz%2FRestDoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Willing-Xyz%2FRestDoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Willing-Xyz","download_url":"https://codeload.github.com/Willing-Xyz/RestDoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238892220,"owners_count":19548152,"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":["javadoc","javadoc-swagger","spring","springboot","springfox","springmvc","swagger","swagger-ui"],"created_at":"2024-09-24T14:06:43.629Z","updated_at":"2025-10-29T21:30:33.462Z","avatar_url":"https://github.com/Willing-Xyz.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## 介绍\r\n\r\n该项目用于在运行时使用javadoc生成swagger文档，并使用 swagger-ui 进行显示。\r\n\r\n\r\n![示例](./images/example_summary.png?)\r\n\r\n## 使用\r\n\r\n第一步, 为SpringBoot项目中配置依赖, 配置RestDocConfig\r\n\r\nMaven项目增加依赖：\r\n\r\n```\r\n\u003cdependency\u003e\r\n     \u003cgroupId\u003ecn.willingxyz.restdoc\u003c/groupId\u003e\r\n     \u003cartifactId\u003eRestDocSpringSwagger3\u003c/artifactId\u003e\r\n     \u003cversion\u003e0.2.1.4\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.github.therapi\u003c/groupId\u003e\r\n    \u003cartifactId\u003etherapi-runtime-javadoc-scribe\u003c/artifactId\u003e\r\n    \u003cversion\u003e0.9.0\u003c/version\u003e\r\n    \u003cscope\u003eprovided\u003c/scope\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n新建配置文件，如下：\r\n\r\n```java \r\n@Configuration\r\n@EnableSwagger3\r\npublic class SwaggerConfig {\r\n    @Bean\r\n    RestDocConfig _swaggerConfig()\r\n    {\r\n            return RestDocConfig.builder()\r\n                    .apiTitle(\"rest doc title\")\r\n                    .apiDescription(\"rest doc desc\")\r\n                    .apiVersion(\"api version\")\r\n                    .packages(Arrays.asList(\"cn.willingxyz.restdoc.spring.examples\"))\r\n                    .build();\r\n    }\r\n}\r\n```\r\n\r\n主要需要修改包名为自己的应用包名。\r\n\r\n[其他配置参考](#配置参考)\r\n\r\n第二步，启用Annotation Processors \r\n\r\n- **IntelliJ IDEA**: File \u003e Settings \u003e Preferences \u003e Build, Execution, Deployment \u003e Compiler \u003e Annotation Processors \u003e 勾选\"Enable annotation processing\".\r\n![编译设置](./images/compile-setting.png?)\r\n\r\n启动应用后，打开 http://host/swagger-ui/index.html 浏览\r\n\r\n具体可参考 [RestDocSpringExamples](https://github.com/Willing-Xyz/RestDoc/tree/master/RestDocSpringExamples)。\r\n\r\n## BeanValidation支持\r\n\r\n如果需要BeanValidation的支持，需要增加以下依赖：\r\n```\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecn.willingxyz.restdoc\u003c/groupId\u003e\r\n    \u003cartifactId\u003eRestDocBeanValidation\u003c/artifactId\u003e\r\n    \u003cversion\u003e0.2.1.4\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n支持BeanValidation的注解：\r\n\r\n- NotNull\r\n- AssertFalse\r\n- AssertTrue\r\n- DecimalMax\r\n- DecimalMin\r\n- Email （不支持正则表达式）\r\n- Max\r\n- Min\r\n- NegativeOrZero\r\n- Negative\r\n- NotBlank\r\n- NotEmpty\r\n- NotNull\r\n- Null\r\n- PositiveOrZero\r\n- Positive\r\n\r\n## Jackson支持\r\n\r\n如果需要Jackson的支持，增加以下依赖：\r\n```\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecn.willingxyz.restdoc\u003c/groupId\u003e\r\n    \u003cartifactId\u003eRestDocJackson\u003c/artifactId\u003e\r\n    \u003cversion\u003e0.2.1.4\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n\r\n支持的Jackson注解：\r\n\r\n- JsonGetter\r\n- JsonSetter\r\n- JsonIgnore\r\n- JsonIgnoreType\r\n- JsonProperty (不支持对枚举的操作)\r\n- JsonIgnoreProperties (仅支持value属性)\r\n\r\n\r\n## 配置参考\r\n\r\n```java \r\n@Bean\r\nRestDocConfig _swaggerConfig()\r\n{\r\n        return RestDocConfig.builder()\r\n                //配置文档标题\r\n                .apiTitle(\"rest doc title\")\r\n                //配置文档描述\r\n                .apiDescription(\"rest doc desc\")\r\n                //配置文档版本\r\n                .apiVersion(\"api version\")\r\n                //是否将类的javadoc解析为swagger显示名称\r\n                .resolveJavaDocAsTypeName(true)\r\n                //是否隐藏没有方法的Controller\r\n                .hideEmptyController(true)\r\n                //配置扫描的包\r\n                .packages(Arrays.asList(\"cn.willingxyz.restdoc.spring.examples\"))\r\n                //启用httpBasic认证\r\n                .httpBasicAuth(new RestDocConfig.HttpBasicAuth(\"restdoc\",\"restdoc\"))\r\n                //配置接口地址\r\n                .servers(Arrays.asList(RestDocConfig.Server.builder().description(\"url desc\").url(\"localhost:8080\").build()))\r\n                //配置field前缀\r\n                .fieldPrefix(\"_\")\r\n                .build();\r\n}\r\n```\r\n\r\n其中 fieldPrefix表示字段前缀。\r\n因为在获取javadoc时，会从field、get方法、set方法上获取，因此如果field有前缀，需要通过fieldPrefix设置，否则将无法获取到javadoc。\r\n如：\r\n\r\n```java\r\npublic class Response {\r\n    /**\r\n    * name javadoc\r\n    */\r\n    private String _name;\r\n    public String getName() {\r\n           return _name;\r\n    }\r\n    public void setName(String name) {\r\n        _name = name;\r\n    }\r\n}\r\n```\r\nName属性对应的字段是_name，因此 fieldPrefix应该设置为 `.fieldPrefix(\"_\")`\r\n\r\n## 使用swagger2\r\n\r\n如果需要使用Swagger2(兼容其他文档工具)，替换依赖为：\r\n```\r\n\u003cdependency\u003e\r\n     \u003cgroupId\u003ecn.willingxyz.restdoc\u003c/groupId\u003e\r\n     \u003cartifactId\u003eRestDocSpringSwagger2\u003c/artifactId\u003e\r\n     \u003cversion\u003e0.2.1.4\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.github.therapi\u003c/groupId\u003e\r\n    \u003cartifactId\u003etherapi-runtime-javadoc-scribe\u003c/artifactId\u003e\r\n    \u003cversion\u003e0.9.0\u003c/version\u003e\r\n    \u003cscope\u003eprovided\u003c/scope\u003e\r\n\u003c/dependency\u003e\r\n```\r\n将EnableSwagger3改为EnableSwagger2\r\n```java\r\n@Configuration\r\n@EnableSwagger2\r\npublic class SwaggerConfig {\r\n    //...\r\n}\r\n```\r\n\r\n\r\n## docker\r\n\r\ndocker通过以下命令运行：\r\n\r\n`docker run --rm -d -p 8084:8084 willingxyz/restdoc:0.2.1.4`\r\n\r\nswagger3规范打开 http://localhost:8084/swagger-ui/index.html 查看。\r\nswagger2规范打开 http://localhost:8084/swagger2-ui/index.html 查看。\r\n\r\n## 原理\r\n\r\n通过注解处理器在编译时生成javadoc的json文件, 将这些文件转换为Swagger-ui的OpenApi数据格式。\r\n\r\n更多信息请参考 [Wiki](https://github.com/Willing-Xyz/RestDoc/wiki)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilling-xyz%2Frestdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilling-xyz%2Frestdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilling-xyz%2Frestdoc/lists"}