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

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，发布浏览都很方便，直接打开网页就可以了

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

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

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

在线测试，便于理解接口结构

响应报文

springboot+swagger2项目搭建

小拉采用 IntelliJ IDEA 创建springboog应用

创建springboot项目

new project->spring初始化器

选择基本模块

在pom.xml添加swagger2依赖

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-swagger-uiartifactId>
  <version>2.2.2version>
dependency>

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-swagger2artifactId>
  <version>2.2.2version>
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 = "用户普通登录
 
 dddd")
    @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 = new Login();
        login.setPassword("123456");
        login.setUserName("login_name");

        System.out.println("f101");
        return new Res(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常用注解说明

更多文章

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