swagger（API接口文档利器）

╰+攻爆jí腚メ 2024-04-07 11:50 95阅读 0赞

### 1、前言 ###

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变  
成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。

很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当自己写的时候确实最烦  
去写接口文档。这种痛苦只有亲身经历才会牢记于心。如果接口文档可以实时动态生成就不会出现上面问题。

写文档也麻烦，那如果可以生成文档呢？Swagger就是做这个事。

Swagger是一个工具，我们使用其可以动态的生成前台和后台功能交互的API规范。

### 2、Swagger介绍 ###

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务([https://swagger.io/][https_swagger.io])。 它的主要作用是：

1.  使得前后端分离开发更加方便，有利于团队协作
2.  接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
3.  功能测试  
    Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

**Swagger工具包括的组件：**

*  Swagger Editor ：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。
 *  Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。
 *  Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
 *  Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
 *  Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

### 3、Springfox ###

使用Swagger时如果碰见版本更新或迭代时，只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。

Marty Pitt编写了一个基于Spring的组件swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。

Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。

Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。

所以在实际开发中，都是直接使用spring-fox。

### 4、Swagger常用注解 ###

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

*  @Api：修饰整个类，描述Controller的作用  
    属性：
    
     *  tags:类的名称。可以有多个值，多个值表示多个副本。
     *  description:描述，已过时。
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口  
    属性：
    
     *  value:接口描述
     *  notes:提示信息
 *  @ApiParam：单个参数的描述信息  
    属性：
    
     *  name:参数名称
     *  value:参数描述
     *  required:是否是必须
 *  @ApiModel：用对象来接收参数  
    属性：
    
     *  value:名称
     *  description:描述
 *  @ApiModelProperty：用对象接收参数时，描述对象的一个字段  
    属性：
    
     *  value :描述
     *  name: 重写属性名
     *  required: 是否是必须的
     *  example: 示例内容
     *  hidden: 是否隐藏。
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数的描述信息
 *  @ApiImplicitParam属性：  
    ![在这里插入图片描述][456c51b5bbf54bc483c8ea61b9021df1.png]

### 5、SpringBoot集成Swagger ###

##### 5.1、引入springfox依赖 #####

<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>

##### 5.2、在项目工程的application.propertis中配置swagger的启动开关 #####

# 开启swagger 
    swagger.enable=true

##### 5.3、在项目工程的config包中添加一个配置类 #####

package cn.bz.wanxinp2p.consumer.config;
    
    import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
    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.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @ConditionalOnProperty(prefix = "swagger",value = {
        "enable"},havingValue = "true")
    @EnableSwagger2  //开启swagger注解支持
    public class SwaggerConfiguration {
        
    
    	@Bean
    	public Docket buildDocket() {
        
    		/**
    		 * Docket:摘要对象，通过对象配置描述文件的信息。
    		 * apilnfo:设置描述文件中info。参数类型Apilnfoe'
    		 * select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
    		 * ApilnfoBuilder: Apilnfo构建器。
    		 */
    		return new Docket(DocumentationType.SWAGGER_2)
    				.apiInfo(buildApiInfo())
    				.select()
    				// 要扫描的API(Controller)基础包
    				.apis(RequestHandlerSelectors.basePackage("cn.bz.wanxinp2p"))
    				.paths(PathSelectors.any())
    				.build();
    	}
    
    	private ApiInfo buildApiInfo() {
        
    		Contact contact = new Contact("pzz","","");
    		return new ApiInfoBuilder()
    				//文档标题
    				.title("P2P应用平台-用户服务API文档")   
    				//文档描述  
    				.description("包含用户服务api")
    				.contact(contact)
    				//文档版本
    				.version("1.0.0").build();
    	}
    }

##### 5.4、在Controller中使用Swagger注解： #####

@RestController
    @Api(value = "用户服务的Controller", tags = "Consumer", description = "用户服务API")
    public class ConsumerController {
        
    
            @ApiOperation("测试hello")
            @GetMapping(path = "/hello")
            public String hello(){
        
                return "hello";
            }
    
            @ApiOperation("测试hi")
            @ApiImplicitParam(name="name",value="姓名",required = true,dataType = "String")
            @PostMapping(value = "/hi")
            public String hi(String name){
        
                return "hi,"+name;
            }
    
    }

##### 5.5、生成文档（查看文档） #####

生成文档是一个HTML页面，需要访问查看。  
项目路径 + swagger-ui.html  
![在这里插入图片描述][3dea952f95354c36a7ac341880178528.png]  
结束！！！！

--------------------

洗脸刷牙应该是每天都做的事情，无论你今天是否出门。

[https_swagger.io]: https://swagger.io/
[456c51b5bbf54bc483c8ea61b9021df1.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/07/5da46fa863f4436c89b1230ff618acb0.png
[3dea952f95354c36a7ac341880178528.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/07/1d4f3a5249024ae68f6922c0bd694fbd.png