{"id":19838878,"url":"https://github.com/sayi/swagger-dubbo","last_synced_at":"2025-04-07T15:05:27.283Z","repository":{"id":24476827,"uuid":"102341886","full_name":"Sayi/swagger-dubbo","owner":"Sayi","description":":page_with_curl: Dubbo的Swagger服务文档","archived":false,"fork":false,"pushed_at":"2024-09-13T20:33:35.000Z","size":1927,"stargazers_count":332,"open_issues_count":21,"forks_count":188,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-03-31T14:09:11.436Z","etag":null,"topics":["dubbo","http","swagger"],"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/Sayi.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":"2017-09-04T09:10:51.000Z","updated_at":"2025-01-16T12:12:00.000Z","dependencies_parsed_at":"2024-12-07T03:15:30.856Z","dependency_job_id":null,"html_url":"https://github.com/Sayi/swagger-dubbo","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayi%2Fswagger-dubbo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayi%2Fswagger-dubbo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayi%2Fswagger-dubbo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sayi%2Fswagger-dubbo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sayi","download_url":"https://codeload.github.com/Sayi/swagger-dubbo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247675597,"owners_count":20977376,"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":["dubbo","http","swagger"],"created_at":"2024-11-12T12:19:24.655Z","updated_at":"2025-04-07T15:05:27.261Z","avatar_url":"https://github.com/Sayi.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Dubbo的Swagger服务文档\n\n## swagger-dubbo\n\n[![Build Status](https://travis-ci.org/Sayi/swagger-dubbo.svg?branch=master)](https://travis-ci.org/Sayi/swagger-dubbo) ![jdk11+](https://img.shields.io/badge/jdk-1.6%2B-orange.svg) ![dubbo3.2.0+](https://img.shields.io/badge/dubbo-2.6.0%2B-blue.svg)\n\nDubbo |ˈdʌbəʊ| 是阿里巴巴提供的分布式框架，Swagger围绕着OpenAPI规范，提供了一套设计、构建、文档化rest api的开源工具。\n\n* 通过swagger阅读接口文档\n* 开发人员可以用它来自测服务接口，也可以用它来模拟别人的服务接口返回值\n* 测试可以用它来验证接口的正确性，基于HTTP进行接口测试\n\n## 前提\n- Apache Dubbo 3.2+\n- JDK 11+\n\n## Maven\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.deepoove\u003c/groupId\u003e\n  \u003cartifactId\u003eswagger-dubbo\u003c/artifactId\u003e\n  \u003cversion\u003e3.0.0-beta\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## SpringBoot\n`@EnableDubboSwagger`开启dubbo的swagger文档。\n\n```java\n@EnableDubboSwagger\npublic class Application {\n\n    public static void main(String[] args) {\n        SpringApplication.run(Application.class, args);\n    }\n}\n```\n\n参见[spring-boot示例](swagger-dubbo-example/dubbo-provider-springboot)\n\n## swagger-ui查看文档\n\n可以在任何能托管页面的容器内集成swagger-ui，配置swagger-dubbo提供的`http://ip:port/context/swagger-dubbo/api-docs`，可能需要跨域支持，详情参见官方文档 [swagger-ui](https://github.com/swagger-api/swagger-ui)\n\n@JKTerrific 在swagger-ui基础上开发了[**swagger-dubbo-ui**](https://github.com/JKTerrific/swagger-dubbo-ui), 解决了页面上的一些展示问题：\n* 参数为model时，输入框变更为输入域，并且支持JSON可视化\n* Model字段为date、byte时，支持展示具体类型，而不是string\n\n![](swagger-dubbo-example/swagger_ui.png)\n\n## 配置\nswagger-dubbo默认无需任何配置，但是也提供了一些可选项。\n\n配置项说明：\n```properties\n#http请求地址，默认为http://ip:port/h/com.XXX.XxService/method\nswagger.dubbo.http=h\n\n#dubbo 服务版本号\nswagger.dubbo.application.version = 1.0\n#dubbo服务groupId\nswagger.dubbo.application.groupId = com.deepoove\n#dubbo服务artifactId\nswagger.dubbo.application.artifactId = dubbo.api\n\n#rpc zk调用 or 本地调用\nswagger.dubbo.cluster = rpc\n\n#是否启用swagger-dubbo，默认为true\nswagger.dubbo.enable = true\n```\n\n## swagger-dubbo集成注意事项\n* 对于服务接口方法重载，为了在http请求中唯一确认一个方法，需要使用注解`@ApiOperation(nickname = \"byArea\")`,通过nickname标记唯一路径(如果不填写，将只显示一个方法)。此时，rest的请求地址为：`http://ip:port/h/com.XXX.XxService/method/byArea`\n[Stackoverflow:重载的方法能够映射到同一URL地址吗](http://stackoverflow.com/questions/17196766/can-resteasy-choose-method-based-on-query-params)\n\n* Object对象作为http请求参数为json string格式。\n[Stackoverflow:POST的方法能够接收多个参数吗？](http://stackoverflow.com/questions/5553218/jax-rs-post-multiple-objects)\n\n* swagger注解既可以写在接口上，也可以写在实现类上。 \n* 原生类型作为http请求参数为必填。\n\n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayi%2Fswagger-dubbo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsayi%2Fswagger-dubbo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsayi%2Fswagger-dubbo/lists"}