前言
使用RESTful服务通常是涉及到多个终端的团队,比如Android、iOS、WEB等。为了让大家沟通顺畅,通常我们需要编写一份详细的RESTful业务接口文档
使用Swagger2有助于我们编写一份详细的RESTful业务接口文档,过去经常会使用Word或者Excel,但是接口非常多,细节又复杂,如果由程序员高质量的输出一个文档,经常耗时长而且效果也不好。Swagger2能将代码和注释说明很好结合在一块。既减轻了研发人员的负担,又能输出高质量的文档。
下面说下如何去使用
pom.xml中添加Swagger2依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
创建Swagger2配置类
@Configuration注解,让Spring来加载该类配置。
@EnableSwagger2注解来启用Swagger2。
apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
RequestHandlerSelectors.basePackage()中填的是你controller的目录
apiInfo()方法中termsOfServiceUrl和contact可以用Contact的对象代替
注意:
Swagger2已经不支持String类型的contact
Contact对象中name表示作者,url通常作为项目的链接,代替之前的termsOfServiceUrl方法,email的话不用我多说了吧,不想写的话可以为空字符串
createRestApi函数创建Docket的Bean之后,apiInfo() 用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
**select()**函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
@Configuration
@EnableSwagger2
public class SwaggerConfig{
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.pjb.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
Contact contact=new Contact("作者名",
"http://zjc.com","email地址");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2")
.description("Hello Swagger2")
//.termsOfServiceUrl("http://www.jianshu.com/u/f192766abeab")
//.contact("作者名")
.contact(contact)
.version("1.0")
.build();
}
}
然后通过创建实体类和controller来简单测试下
@RestController
@RequestMapping("user")
public class UserController {
@Autowired
UserService userService;
@GetMapping(value="/findAll")
@ApiOperation(value = "查询所有用户",httpMethod ="GET", response = User.class,notes = "HelloWorld")
public List<User> findAll(){
return userService.findAll();
}
}
注意:
记得在UserController中需要id输入的方法的注解少了个参数配置: paramType=“path”,不然所有的参数类型都会是body,获取不到请求参数。例如
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Long”,paramType = “path”);
访问:http://localhost:8080/swagger-ui.html
就能看到前文所展示的RESTful API的页面。
我们还可以进行Try it out 进行测试,赶紧试试吧,满意请点赞收藏,么么哒
这里是一个真诚的***青年技术交流QQ群:761374713***,不管你是大学生、社畜、想学习变成的其他人员,欢迎大家加入我们,一起成长,一起进步,真诚的欢迎你,不管是技术,还是人生,还是学习方法。有道无术,术亦可求,有术无道,止于术。