RESTful API（三）——使用Swagger 2构建RESTful API文档

拼搏现实的明天。 2021-12-17 00:41 492阅读 0赞

## 一、传统API接口文档存在问题 ##

1、由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。

2、随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

为了解决上面的问题，可以采用Swagger2。它最大的特色在于，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。

## 二、Spring Boot整合Swagger2 ##

**添加Swagger2依赖**

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

**创建Swagger2配置类**

package com.springboot.api.core.config;
    
    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;
    
    /**
     * 
     * @method Swagger2配置类
     * @author Mr yi
     * @time 2019年4月29日
     */
    @Configuration //标记配置类
    @EnableSwagger2 //开启在线接口文档
    public class Swagger2Config {
        /**
         * 添加摘要信息(Docket)
         */
        @Bean
        public Docket controllerApi() {
            return new Docket(DocumentationType.SWAGGER_2)
            		.apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.springboot.api.api"))
                    .paths(PathSelectors.any())
                    .build();
        }
        
        @SuppressWarnings("deprecation")
    	private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("标题：IT菜鸟_接口文档")
                    .description("描述：用于IT菜鸟相关项目API接口文档，访问地址：http://localhost:8006/spring-api/swagger-ui.html")
                    .contact("Mr yi")
                    .version("版本号:v1.0")
                    .build();
        }
    }

@Configuration注解：让Spring Boot来加载该类配置。

@EnableSwagger2注解：启用Swagger2。

@Bean注解：让Docket函数创建类型为Docket的Bean

apiInfo()方法：用来创建该API的基本信息（这些信息最后会展现在文档页面中）。

select()函数：返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义——Swagger会扫描该包下（com.springboot.api.api）所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

package com.springboot.api.api.test.controller;
    
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.Iterator;
    import java.util.List;
    import java.util.Map;
    import java.util.Map.Entry;
    
    import org.springframework.web.bind.annotation.DeleteMapping;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.PutMapping;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    import com.springboot.api.api.test.entity.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    
    @Api(tags = "用户信息接口")
    @RestController
    @RequestMapping("/user")
    public class UserController {
    
    	/**
    	 * 模拟测试数据
    	 */
    	static Map<Integer, User> users = new HashMap<>();
    
    	 static  
    	{
    		User user1 = new User(1, "admin", "123456");
            User user2 = new User(2, "lisi", "111111");
            User user3 = new User(3, "wangwu", "123456");
            users.put(1,user1);
            users.put(2,user2);
            users.put(3,user3);
     
    	}
    
    	@ApiOperation("获取列表")
    	@RequestMapping(value={""}, method=RequestMethod.GET)
    	public List<User> userList() {
    		List<User> list= new ArrayList<User>();
    		Iterator<Entry<Integer, User>>  iter = users.entrySet().iterator();
    		while (iter.hasNext()) {
    			Entry<Integer, User> entry = iter.next();
    			list.add(entry.getValue());
    		}
    		return list;
    	}
    
    	@ApiOperation(value="新增用户", notes="根据User对象创建用户")
    	@ApiImplicitParam(name = "User", value = "用户详细实体user", required = true, dataType = "User")
    	@RequestMapping(value="", method=RequestMethod.POST)
    	public User save(User user) {
    		users.put(user.getUserId(), user);
    		return user;
    	}
    
    	@ApiOperation(value="获取用户详细信息", notes="根据id来获取用户详细信息")
        @ApiImplicitParam(paramType="path" ,name = "id", value = "用户ID", required = true, dataType = "Integer")
        @RequestMapping(value="/{id}", method=RequestMethod.GET)
        public User getUser(@PathVariable Integer id) {
    		return users.get(id);
        }
    	
    	@ApiOperation(value="更新用户", notes="根据id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
        @ApiImplicitParams({
                @ApiImplicitParam(paramType="path" ,name = "id", value = "用户ID", required = true, dataType = "Integer"),
                @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
        })
        @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    	public User  update(@PathVariable Integer id, @RequestBody User user	) {
    		User u = users.get(id);
    		u.setUsername(user.getUsername());
    		u.setPassword(user.getPassword());
    		users.put(id, u);
    		return u;
    	}
    
    	@ApiOperation(value="删除用户", notes="根据id来指定删除对象")
        @ApiImplicitParam(paramType="path" ,name = "id", value = "用户ID", required = true, dataType = "Integer")
    	@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
        public String deleteUser(@PathVariable Integer id) {
    		users.remove(id);
            return "success";
        }
    	
    	 
    	
    }

启动程序

[http://localhost:8006/springboot-api/swagger-ui.html][http_localhost_8006_springboot-api_swagger-ui.html]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTE0ODM3_size_16_color_FFFFFF_t_70]

## 三、Swagger2注解使用教程 ##

@Api：用在请求的类上，表示对类的说明
        tags="说明该类的作用，可以在UI界面上看到的注解"
        value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
    
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
    
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · body（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值
    
    @ApiResponses：用在请求的方法上，表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
            code：数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类
    
    @ApiModel：用于响应类上，表示一个返回响应数据的信息
                （这种一般用在post创建的时候，使用@RequestBody这样的场景，
                请求参数无法使用@ApiImplicitParam注解进行描述的时候）
        @ApiModelProperty：用在属性上，描述响应类的属性
    
    
    @Api：用在请求的类上，说明该类的作用
        tags="说明该类的作用"
        value="该参数没什么意义，所以不需要配置"

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

如果你觉得本篇文章对你有所帮助的话，麻烦请点击头像右边的关注按钮，谢谢！

技术在交流中进步，知识在分享中传播

[http_localhost_8006_springboot-api_swagger-ui.html]: http://localhost:8006/springboot-api/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI5OTE0ODM3_size_16_color_FFFFFF_t_70]: /images/20211214/b14d96f492ac45a780d68af660192312.png