03-10 03:04 阅读 76

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

1、为什么要写Api文档

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

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

2、写Api文档很头疼吗

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

3、Swagger2

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

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

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

4、接口介绍

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

5、引入依赖


            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2

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 getUserInfo(@ApiParam(value = "用户ID") @PathVariable("id") String id) {

        User userInfo = userService.getUserInfo(id);
        Result result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(userInfo);

        return result;
    }

}

https://www.cnblogs.com/w84422/p/15194549.html

原文：https://www.cnblogs.com/luweiweicode/p/15203202.html