前言

在前后端分离的开发中，后端只负责业务开发，而前端负责页面的设计以及数据的接入，前端需要后端的接口地址才能完成数据的接入。为了减少前后端开发人员的沟通成本，都会构建一份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，代码如下：

扫描二维码关注公众号，回复： 12467255 查看本文章

@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官网。

文章目录

前言