spring boot ＋Swagger-ui 自动生成API文档

一时失言乱红尘 2021-12-14 03:23 400阅读 0赞

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

这样后段开发好了api 之后就要提交api 文档给前端的朋友。给前端的api 文档各个公司有各个公司的要求，有的是word 有的是 md 文档，或者是 postman 的一个连接。

好了废话不多说说一下 swagger -ui 吧

什么是Swagger  
Swagger是一个Restful风格接口的文档在线自动生成和测试的框架   
官网：http://swagger.io   
官方描述：The World’s Most Popular Framework for APIs.

先看一下 swagger-ui 生成的api 的效果吧（这是一个增删改查的小例子）  
![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NDY5MDU1_size_16_color_FFFFFF_t_70][]

然后我们打开查询所有用户的api 看到api 内容

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NDY5MDU1_size_16_color_FFFFFF_t_70 1][]

然后在服务器运行的状态下点击 try it out 测试查询功能

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NDY5MDU1_size_16_color_FFFFFF_t_70 2][]

好了这个就是自动生成的api 效果。接下来我们就看怎么在我们的项目中使用swagger-ui 吧

## **springboot 集成 swagger -ui** ##

### **1、添加依赖** ###

>     <dependency>
>         <groupId>io.springfox</groupId>
>         <artifactId>springfox-swagger2</artifactId>
>         <version>2.2.2</version>
>     </dependency>
>     
>     <dependency>
>         <groupId>io.springfox</groupId>
>         <artifactId>springfox-swagger-ui</artifactId>
>         <version>2.2.2</version>
>     </dependency>

### **2、编写配置文件** ###

在application 同级目录新建 Swagger2 文件

>     package com.github.springbootmybatis;
>     
>     import org.springframework.context.annotation.Bean;
>     import org.springframework.context.annotation.Configuration;
>     import springfox.documentation.builders.ApiInfoBuilder;
>     import springfox.documentation.builders.PathSelectors;
>     import springfox.documentation.builders.RequestHandlerSelectors;
>     import springfox.documentation.service.ApiInfo;
>     import springfox.documentation.spi.DocumentationType;
>     import springfox.documentation.spring.web.plugins.Docket;
>     import springfox.documentation.swagger2.annotations.EnableSwagger2;
>     
>     /**
>      * Created by lizhangyu on 2019/07/08
>      */
>     @Configuration
>     @EnableSwagger2
>     public class Swagger2 {
>         /**
>          * 创建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.github.springbootmybatis.controller"))
>                     .paths(PathSelectors.any())
>                     .build();
>         }
>     
>         /**
>          * 创建该API的基本信息（这些基本信息会展现在文档页面中）
>          * 访问地址：http://项目实际地址/swagger-ui.html
>          * @return
>          */
>         private ApiInfo apiInfo() {
>             return new ApiInfoBuilder()
>                     .title("Spring Boot中使用Swagger2构建RESTful APIs")
>                     .description("更多请关注https://blog.csdn.net/qq_37469055")
>                     .termsOfServiceUrl("https://blog.csdn.net/qq_37469055")
>                     .contact("lizhangyu")
>                     .version("1.0")
>                     .build();
>         }
>     }

### 3、在controller上添加注解，自动生成API ###

>     package com.github.springbootmybatis.controller;
>     
>     import com.github.springbootmybatis.entity.City;
>     import com.github.springbootmybatis.service.CityService;
>     import io.swagger.annotations.Api;
>     import io.swagger.annotations.ApiOperation;
>     import org.springframework.beans.factory.annotation.Autowired;
>     import org.springframework.web.bind.annotation.RequestMapping;
>     import org.springframework.web.bind.annotation.RequestMethod;
>     import org.springframework.web.bind.annotation.RequestParam;
>     import org.springframework.web.bind.annotation.RestController;
>     
>     import java.util.Date;
>     
>     @RestController
>     @RequestMapping("/test")
>     @Api(value = "城市的增删改查")
>     public class CityRestController {
>     
>         @Autowired
>         private CityService cityService;
>     
>         @RequestMapping("/hello")
>         @ApiOperation(value = "测试SpringBoot项目")
>         public String hello(){
>             return "你好";
>         }
>     
>         /**
>          * 根据id
>          * @param id 查询城市
>          * @return
>          */
>         @RequestMapping(value = "/findById", method = RequestMethod.POST)
>         @ApiOperation(value = "获取城市")
>         public City findById(@RequestParam int id){
>             return cityService.selectByPrimaryKey(id);
>         }
>     
>     }

注解含义：

> @Api：用在类上，说明该类的作用。
> 
> @ApiOperation：注解来给API增加方法说明。
> 
> @ApiImplicitParams : 用在方法上包含一组参数说明。
> 
> @ApiImplicitParam：用来注解来给方法入参增加说明。
> 
> @ApiResponses：用于表示一组响应
> 
> @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
> 
>       code：数字，例如400
> 
>       message：信息，例如"请求参数没填好"
> 
>       response：抛出异常的类   
> 
> @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）  
> @ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

![70][]

paramType会直接影响程序的运行期，如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。

本文项目全部代码：[https://github.com/li-zhang-yu/spring-boot-test][https_github.com_li-zhang-yu_spring-boot-test]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NDY5MDU1_size_16_color_FFFFFF_t_70]: /images/20211213/09bc252c7ccb4ebfbd08e07938ac8c00.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NDY5MDU1_size_16_color_FFFFFF_t_70 1]: /images/20211213/a8c9583f99aa40f7a807274929b9c0d9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM3NDY5MDU1_size_16_color_FFFFFF_t_70 2]: /images/20211213/693a3719d33f48d9857b33c7c1e5b8c1.png
[70]: /images/20211213/309a342ceb8c4c8f8d4be411b66be5f9.png
[https_github.com_li-zhang-yu_spring-boot-test]: https://github.com/li-zhang-yu/spring-boot-test