文章目录
前言
在前后端分离的开发中，后端只负责业务开发，而前端负责页面的设计以及数据的接入，前端需要后端的接口地址才能完成数据的接入。为了减少前后端开发人员的沟通成本，都会构建一份API文档，里面有项目的所有接口的详细信息。利用文档就能够描述所有的接口信息，但是会有很大的不足。例如项目的接口众多，编写文档的工作量就会很大，编写接口信息并不只是写接口的地址就可以了，还要写接口请求参数以及参数的类型，返回值以及相应的状态码等。文档维护极其不方便，修改了某个接口当中的代码，要在众多的接口文档中找出相应的接口文档信息进行相应的修改。
swagger提供了一个全新的构建api文档的方式，利用少量的注解就能根据代码自动生成接口文档，并且提供了接口测试，使得后端的开发人员只关注业务处理，而不是繁杂的文档撰写。
一、使用步骤
1.创建SpringBoot项目
详细的创建SpringBoot项目的步骤可以参考这篇博客：利用idea创建SpringBoot项目
2.导入Swagger相关的依赖
Swagger相关的依赖如下：
<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>
3.配置Swagger2
创建Swagger2的配置类SwaggerConfig，代码如下：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build().apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("项目接口文档")
.description("xx项目的接口文档")
.version("v1.0")
.contact(new Contact("喂喂，要加油","https://www.csdn.net","[email protected]"))
.build();
}
}
@Configuration注解代表这是一个配置类，@EnableSwagger2注解代表开启Swagger。apis(RequestHandlerSelectors.basePackage(“com.example.demo.controller”)表示配置要扫描的controller位置。apiInfo方法用来配置你的个人信息以及项目的信息等。
项目的结构图如下：
运行程序，在浏览器中输入：http://localhost:8080/swagger-ui.html，进入接口文档，从文档可以看见配置的项目信息以个人信息等。
4.接口开发-根据书籍号查询书籍名称
在controller包下新建一个BookController类，代码如下：
@RestController
@Api(tags = "书籍数据接口")
public class BookController {
@ApiOperation(value = "查询数据",notes = "根据数据编号查询数据名称")
@ApiImplicitParam(paramType = "path",name = "bookId",value = "书籍编号",required = true)
@GetMapping("book/{bookId}")
public String getBookName(@PathVariable Integer bookId){
if (bookId == 1){
return "《编译原理》";
}else if (bookId == 2){
return "《JAVA虚拟机规范》";
}else {
return "没有查询到相关的书籍！";
}
}
@Api(tags = “书籍数据接口”)描述这个Controller类的信息。@ApiOperation注解用来描述一个方法的基本信息，其中value用来简短的描述信息，notes用来详细描述方法的信息。
@ApiImplicitParam注解用来描述方法的参数，paramType用来描述方法的参数放在哪个地方，取值如下：
- path：参数获取方式@PathVariable
- query:参数获取方式@RequestParam
- header:参数获取方式@RequestHeader
- body
- form
取值不正确会影响测试。
name为参数变量，value用来描述参数信息，required = true表示使用此接口时必须要传入相应的参数。
启动项目会看见如下图所示的接口信息。
点击Try it out可以测试接口。输入书籍编号2就能够返回《编译原理》。
5.接口开发-根据书籍号删除相应的书籍信息
同样在BookController类中新增以下代码：
@ApiResponses({
@ApiResponse(code = 200,message = "删除成功"),
@ApiResponse(code = 501,message = "删除失败")
})
@ApiOperation(value = "删除数据",notes = "根据书籍编号删除相应的书籍")
@ApiImplicitParam(paramType = "path",name = "bookId",value = "书籍编号",required = true)
@DeleteMapping("/book/delete/{bookId}")
public String deleteBook(@PathVariable Integer bookId){
return "成功删除！";
}
@ApiResponses用来放入多个@ApiResponse注解。@ApiResponse用来描述状态码以及相应的信息，如果只有一个@ApiResponse注解则可以不用写在@ApiResponses里。
启动程序，api文档如下：
6.接口开发-增加书籍信息（使用到实体类）
新建实体类Book，代码如下：
@ApiModel(value = "书籍实体类",description = "书籍信息")
public class Book {
@ApiModelProperty(value = "书籍名称")
private String bookName;
@ApiModelProperty(value = "书籍id")
private Integer bookId;
public String getBookName() {
return bookName;
}
public void setBookName(String bookName) {
this.bookName = bookName;
}
public Integer getBookId() {
return bookId;
}
public void setBookId(Integer bookId) {
this.bookId = bookId;
}
}
@ApiModel注解用来描述实体类的信息，@ApiModelProperty注解用来描述成员变量的信息。
在BookController类中新增一下方法：
@ApiOperation(value = "增加数据",notes = "增加相应的书籍")
@PutMapping("/book/insert")
public String insertBook(@RequestBody Book book){
return "成功！";
}
启动程序，接口信息如下：
实体类的信息如下：
总结
本文只是列举了一些常用的用法，其它的用法可以进入swagger官网。