Swagger是一个简单易用的工具,不仅为我们的API调用生成文档,还提供了一个可以援引这些文档的易用的web客户端。
在SpringMvc中,可以通过Swagger文档工具来生产开放的API文档,供公开使用。
加入Maven依赖
首先在pom文件中指定Swagger:
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
配置Swagger
接下来,需要告诉Swagger想要为哪些控制器类生成文档。我们需要引入一个称为SwaggerConfig的新类,它包含Swagger的各种配置。
package cn.zealon.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
/**
* Swagger全局配置
* @auther: Zealon
* @Date: 2017-10-14 16:13
*/
@Configuration
@EnableSwagger
public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation() {
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
"API 示例",
"My Apps API Description",
"My Apps API terms of service",
"zealon@126.com",
"My Apps API Licence Type",
"My Apps API License URL"
);
return apiInfo;
}
}
引入Swagger UI静态文件
静态文件,可以到Github中去下载最新版本。
下载地址:swagger-ui
下载后,把dist文件夹,拷贝到spring工程的静态资源文件中即可。
然后进入dist/index.html修改数据源url地址:
https://petstore.swagger.io/v2/swagger.json修改为,
http://localhost:8080/api-docs,也就是你项目的地址。
Controller配置Swagger注解
最后,在需要增加API说明的控制器类中,增加Swagger的注解来进行描述。
@Api,整个类说明 @ApiOperation,类中的方法说明
package cn.zealon.controller;
import cn.zealon.entity.User;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
/**
* @auther: Zealon
* @Date: 2017-10-14 16:31
*/
@RestController
@RequestMapping("sample")
@Api(value="sample")
public class SampleController {
@GetMapping("/getUserById")
@ApiOperation(value = "通过ID查询User信息", httpMethod = "GET", notes = "暂无")
public String getUserById(@ApiParam(required = true, name = "id", value = "用户ID") String id) {
return "id:"+id;
}
@PostMapping("saveUser")
@ApiOperation(value = "保存用户信息", httpMethod = "POST",response = User.class, notes = "暂无")
public String saveUser(@ApiParam(required = true, name = "paramData", value = "用户信息") @RequestBody User paramData) {
return paramData.toString();
}
}
测试
启动工程,访问swagger静态资源下的index.html。
如图:
点击任意一个方法,可以看到请求类型、说明、参数等等,点击Try,便可进行测试了。
你还可以用Swagger做许多事情,更多详情可以去查看它的官方文档(https://swagger.io)。
作者: Zealon
崇尚简单,一切简单自然的事物都是美好的。