mirror of
https://gitee.com/wangkang/udf.git
synced 2026-10-22 07:03:50 +00:00
160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
# spring boot / cloud (三) 集成springfox-swagger2构建在线API文档
|
|
|
|
##前言
|
|
|
|
###不能同步更新API文档会有什么问题?
|
|
|
|
>理想情况下,为所开发的服务编写接口文档,能提高与周边系统对接联调的效率.但前提条件是,服务和API文档必须是同步更新的,如果不能保证同步,那接口文档就会流于形式,不仅不能起到应有的作用,甚至某些情况下,甚至会误导对接的系统,导致更低效率的沟通.
|
|
|
|
##思路
|
|
|
|
- 根据现有的服务定义来自动生成接口文档
|
|
|
|
##实现
|
|
|
|
###1.pom.xml集成springfox-swagger2
|
|
|
|
|
|
``` xml
|
|
<!-- swagger2 -->
|
|
<dependency>
|
|
<groupId>io.springfox</groupId>
|
|
<artifactId>springfox-swagger2</artifactId>
|
|
<version>${springfox-swagger2.version}</version>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>io.springfox</groupId>
|
|
<artifactId>springfox-swagger-ui</artifactId>
|
|
<version>${springfox-swagger2.version}</version>
|
|
</dependency>
|
|
```
|
|
|
|
###2.创建Swagger2Config类
|
|
|
|
``` java
|
|
@Configuration
|
|
@EnableSwagger2
|
|
public class Swagger2Config {
|
|
|
|
|
|
}
|
|
```
|
|
|
|
|
|
###3.配置Bean
|
|
|
|
``` java
|
|
@Bean
|
|
public WebMvcConfigurerAdapter addResourceHandlers() {
|
|
return new WebMvcConfigurerAdapter() {
|
|
@Override
|
|
public void addResourceHandlers(ResourceHandlerRegistry registry) {
|
|
registry.addResourceHandler("swagger-ui.html")
|
|
.addResourceLocations("classpath:/META-INF/resources/");
|
|
registry.addResourceHandler("/webjars/**")
|
|
.addResourceLocations("classpath:/META-INF/resources/webjars/");
|
|
}
|
|
};
|
|
}
|
|
```
|
|
|
|
注意点 : 版本号和项目名称可在配置文件中定义(从pom中取)
|
|
|
|
``` java
|
|
@Bean
|
|
public Docket createRestApi() {
|
|
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
|
|
.apis(RequestHandlerSelectors.basePackage("org.itkk")).paths(PathSelectors.any())
|
|
.build();
|
|
}
|
|
|
|
private ApiInfo apiInfo() {
|
|
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
|
|
apiInfoBuilder.title(this.projectName + " online api document");
|
|
apiInfoBuilder.version(version);
|
|
return apiInfoBuilder.build();
|
|
}
|
|
```
|
|
|
|
###4.使用@Api来标记controller
|
|
|
|
``` java
|
|
@RestController
|
|
@RequestMapping("demo")
|
|
@Api(value = "demo",
|
|
consumes = "application/json",
|
|
produces = "application/json",
|
|
protocols = "http")
|
|
public class DemoController {
|
|
|
|
}
|
|
```
|
|
|
|
###5.使用@ApiOperation来标记方法
|
|
|
|
``` java
|
|
@ApiOperation(value = "add", notes = "add")
|
|
@RequestMapping(value = "add", method = RequestMethod.GET)
|
|
public RestResponse<Integer> add(Integer a, Integer b) {
|
|
return new RestResponse<>(demoService.add(a, b));
|
|
}
|
|
```
|
|
|
|
###6.使用@ApiImplicitParams和@ApiImplicitParam来标参数
|
|
|
|
``` java
|
|
@ApiOperation(value = "add", notes = "add")
|
|
@ApiImplicitParams({
|
|
@ApiImplicitParam(paramType = "query", name = "a", value = "a", required = true,
|
|
dataType = "int"),
|
|
@ApiImplicitParam(paramType = "query", name = "b", value = "a", required = true,
|
|
dataType = "int") })
|
|
@RequestMapping(value = "add", method = RequestMethod.GET)
|
|
public RestResponse<Integer> add(Integer a, Integer b) {
|
|
return new RestResponse<>(demoService.add(a, b));
|
|
}
|
|
```
|
|
|
|
###7.使用@ApiModel和@ApiModelProperty来标实体类
|
|
|
|
``` java
|
|
@ApiModel(description = "响应消息体")
|
|
public class RestResponse<T> implements Serializable {
|
|
|
|
/**
|
|
*
|
|
* 描述 : id
|
|
*
|
|
*/
|
|
private static final long serialVersionUID = 1L;
|
|
|
|
/**
|
|
* 描述 : 响应ID
|
|
*/
|
|
@ApiModelProperty(value = "响应ID", required = true, dataType = "string")
|
|
private String id = UUID.randomUUID().toString();
|
|
|
|
.............
|
|
|
|
}
|
|
```
|
|
|
|
## **代码仓库** (博客配套代码)
|
|
|
|
- [udf-starter : 基础项目,脚手架,框架](https://gitee.com/wangkang/udf)
|
|
|
|
- [udf-sample : 集成样例](https://gitee.com/wangkang/udf-sample)
|
|
|
|
##结束
|
|
|
|
以上配置结束之后,启动项目,访问`http://xxxxx/swagger-ui.html`即可能够访问接口文档,并且直接可以做接口调用测试.
|
|
|
|
然后对于Swagger2这个组件,目前看下来就是对业务代码有一定的入侵,总之使用前请根据自身项目情况做好评估,不要盲目跟风.
|
|
|
|
---------
|
|
|
|
想获得最快更新,请关注公众号
|
|
|
|
|
|
|