打造完美接口文档 - 应用springboot+swagger2编写restFull接口文档

怼烎@ 2022-06-11 00:37 397阅读 0赞

APP开发免不了和服务器打交道，接口文档就成了APP与服务器沟通的规范文书。随着业务扩大和需求的不断变更，接口文档也会变更。在小拉之前参加的项目中，接口文档通常是用word。由于服务器开发人员不用git，所以接口文档的传递就只有邮盘了。这就造成接口文档更新不及时，文档拷贝泛滥。加上接口文档的编写也不够规范，给开发人员造成了不少的麻烦。

# 什么才是好用的接口文档？ #

1.  及时性 (接口变更后，能够及时准确地通知相关开发人员)
2.  规范性 (能够规范表达接口的地址，请求方式，参数及响应格式和错误信息)
3.  一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4.  可测性 (接口能够测试，以方便理解业务)

# 你的项目中用哪种方式？ #

1.  word文档方式
2.  git markdown方式
3.  第三方在线接口管理（easyApi, 小幺鸡等，sosoApi）
4.  springboot+swagger2

word的方式: 是小拉项目组采用的方式，在项目前期做概要设计和细设过程中，通常采用这种方式，但是在项目后期，这种方式的问题就出来了，它无法适应接口的频繁变更，和文档分发过程中的版本控制。

git + markdown方式: markdown现在很流行了。简单的语法，不用关心排版问题且样式规范，又有代码的高亮，浏览器直接打开。markdown文件本质就是文本，便于版本管理，应用github或coding.net，发布浏览都很方便，直接打开网页就可以了

![2017-07-26-084758.jpg][]

第三方接口管理平台，也是不错的选择。需要开发人员都注册帐号，小拉试用了一下感觉还可以，不是太好用。

springboot+swagger2,小拉认为是目前比较完美的接口文档方式，界面美观规范，可测试

![2017-07-26-085613.jpg][]

响应结构模型，接口说明支持html

![2017-07-26-090004.jpg][]

在线测试，便于理解接口结构  
![2017-07-26-090240.jpg][]

响应报文  
![2017-07-26-090326.jpg][]

# springboot+swagger2项目搭建 #

小拉采用 IntelliJ IDEA 创建springboog应用

## 创建springboot项目 ##

new project->spring初始化器  
![2017-07-26-090726.jpg][]

选择基本模块  
![2017-07-26-090930.jpg][]

## 在pom.xml添加swagger2依赖 ##

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

## 添加 SwaggerConfig.java ##

package com.ruglcc.swagger;
    
    import com.google.common.base.Predicates;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.context.request.async.DeferredResult;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     *  swagger2 配置类
     * Created by ruglcc on 2017/7/8.
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        
    
        /**
         * 可以定义多个组，比如本类中定义把test和demo区分开了
         * （访问页面就可以看到效果了）
         *
         */
        @SuppressWarnings("unchecked")
        @Bean
        public Docket f1xxDocket(){
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .forCodeGeneration(true)
                    .select()
                    .paths(PathSelectors.regex("/api/f[1-9][0-9][0-9]"))
                    .build()
                    .apiInfo(f1xxApiInfo());
    
            return docket;
        }
    
    
    
        private ApiInfo f1xxApiInfo() {
            ApiInfo apiInfo = new ApiInfo("大标题",//大标题
                    "用户管理相关接口",//小标题
                    "v1.0",//版本
                    "描述",
                    "ruglcc",//作者
                    "ruglcc",//链接显示文字
                    "http://blog.csdn.net/ruglcc"//网站链接
            );
    
            return apiInfo;
        }
    }

## 编写接口文档 ##

F1xxController.java

package com.ruglcc.controller;
    
    
    import com.ruglcc.bean.Login;
    import com.ruglcc.bean.Res;
    import io.swagger.annotations.*;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    
    @RestController
    @RequestMapping("/api")
    @Api(value = "F1 用户管理", description = "用户注册，登录，身份认证，上传头像等")
    public class F1xxController {
        
    
        @RequestMapping("/f101")
        @ApiOperation(value = "f101 用户登录",
                httpMethod = "POST",
                notes = "用户普通登录<br> <hr> <font color = red>dddd</font>")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "user_name", value = "登录用户名", required = true, dataType = "String"),
                @ApiImplicitParam(name = "password", value = "登录密码", required = true, dataType = "String"),
        })
        @ApiResponses({
                @ApiResponse(code = 200, message = "消息错误")
        })
        public Res<Login> login(){
    
            Login login = new Login();
            login.setPassword("123456");
            login.setUserName("login_name");
    
            System.out.println("f101");
            return new Res<Login>(0,"", login);
        }
    }

## 编写模型的文档 ##

package com.ruglcc.bean;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    /**
     * 响应报文结构基类
     * Created by ruglcc on 2017/7/11.
     */
    @ApiModel
    public class ResBase {
        
    
        /**
         * 错误码
         */
        @ApiModelProperty(value = "错误码", required = true, position = 0)
        private Integer code;
    
        /**
         * 错误消息
         */
        @ApiModelProperty(value = "错误信息", required = true, position = 1)
        private String  msg;
    
    
    
        public Integer getCode() {
            return code;
        }
    
        public void setCode(Integer code) {
            this.code = code;
        }
    
        public String getMsg() {
            return msg;
        }
    
        public void setMsg(String msg) {
            this.msg = msg;
        }
    
        public ResBase(Integer code, String msg) {
            this.code = code;
            this.msg = msg;
        }
    }

## 常用文档注解 ##

[swagger常用注解说明][swagger]

## 更多文章 ##

[ 打造完美接口文档 - 发布springboot应用到阿里云服务器][_ - _springboot]

[2017-07-26-084758.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-084758.jpg
[2017-07-26-085613.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-085613.jpg
[2017-07-26-090004.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-090004.jpg
[2017-07-26-090240.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-090240.jpg
[2017-07-26-090326.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-090326.jpg
[2017-07-26-090726.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-090726.jpg
[2017-07-26-090930.jpg]: http://ohag8y1i2.bkt.clouddn.com/2017-07-26-090930.jpg
[swagger]: http://www.jianshu.com/p/12f4394462d5
[_ - _springboot]: http://blog.csdn.net/ruglcc/article/details/76147645