有了Swagger2，再也不用为写Api文档头疼了

野性酷女 2022-09-09 00:21 156阅读 0赞

## 1、为什么要写Api文档 ##

现在，前后端分离的开发模式已经非常流行，后端开发工程师只负责完成后端接口，前端页面的开发和渲染完全由前端工程师完成。

问题来了，前端工程师怎么知道后端接口的具体定义呢？答案是由后端工程师撰写。

## 2、写Api文档很头疼吗 ##

答案是一定的，这对后端工程师来说，是额外的工作，编码已经很耗费精力了，这时前端工程师来催文档，不头疼才怪：），当然这也不是前端工程师的问题，都是为项目的进度着急。

## 3、Swagger2 ##

现在好了，一个自动撰写Api文档的神器出现了，他就是 Swagger2，Swagger2通过美观的WEB界面展示了所有接口的定义，非常方便，还能直接在界面上进行测试调用，有助于调试。

后端工程师，定义好接口，加几个注解，便能自动生成在线接口定义，前端工程师可以实时的看到。

下面就来讲讲如何把 Swagger2 整合到项目中来。

## 4、接口介绍 ##

这里以一个简单的接口作为例子，接口的功能是输入用户ID，获取用户数据。

## 5、引入依赖 ##

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

## 6、增加Swagger2配置类 ##

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
    @EnableSwagger2
    public class Swagger2 { 
    
    // swagger2配置
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)  // 指定api类型为swagger2
                        .apiInfo(apiInfo())                 // 用于定义api文档汇总信息
                        .select()
                        .apis(RequestHandlerSelectors
                                .basePackage("cn.zhuifengren.controller"))   // 指定扫描的controller包
                        .paths(PathSelectors.any())         // 所有controller
                        .build();
        }
    
       private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("hello工程接口api")        // 文档页标题
                    .contact(new Contact("hello",
                            "",
                            ""))        // 联系人信息
                    .description("专为hello工程提供的api文档")  // 详细信息
                    .version("1.0.0")   // 文档版本号
                    .termsOfServiceUrl("") // 网站地址
                    .build();
        }
    
    }

## 7、在Controller类中增加Swagger2注解 ##

import cn.zhuifengren.model.Result;
    import cn.zhuifengren.model.User;
    import cn.zhuifengren.service.UserService;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @RequestMapping("/user")
    @Api(value = "UserController", tags = "用户接口")
    public class UserController { 
    
        @Autowired
        private UserService userService;
    
        @GetMapping("/info/{id}")
        @ApiOperation(value = "获取用户信息")
        public Result<User> getUserInfo(@ApiParam(value = "用户ID") @PathVariable("id") String id) { 
    
            User userInfo = userService.getUserInfo(id);
            Result<User> result = new Result<>();
            result.setCode(200);
            result.setMessage("success");
            result.setData(userInfo);
    
            return result;
        }
    
    }

其中 @Api注解 放在类上，用于对类的描述，@ApiOperation注解 放在方法上，用于对接口方法的描述。

## 8、模型类中增加Swagger2注解 ##

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    @ApiModel(value = "用户实体", description = "用户实体")
    public class User { 
    
        @ApiModelProperty(value = "用户id", name = "id", example = "1")
        private String id;
        @ApiModelProperty(value = "用户姓名", name = "name", example = "小李")
        private String name;
        @ApiModelProperty(value = "用户年龄", name = "age", example = "36")
        private Integer age;

其中 @ApiModel注解 放在类上，用于对模型类的描述，@ApiModelProperty注解 放在属性上，用于对模型属性的描述。

## 9、启动项目查看效果 ##

启动项目后，进入地址：http://localhost:8080/swagger-ui.html，即可看到Swagger2 WEB页面，点击【Try it out】按钮，还可以对接口进行测试，是不是很方便呢，赶快去用一下吧  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA6L-96aOO5Lq66IGK57yW56iL_size_20_color_FFFFFF_t_70_g_se_x_16]

[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA6L-96aOO5Lq66IGK57yW56iL_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220829/8321cce0c3e74a08b8450c37d328229c.png