前言

Spring Boot由于构建快的特点可以很方便地用来写RESTful API，结合Swagger2可以快速构建API文档。

开始创建

pom.xml

<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>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>

Swagger2Config

package com.asiainfo.aigov;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.asiainfo.aigov.system.web.session.UserSession;

import io.swagger.annotations.ApiOperation;
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;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .ignoredParameterTypes(UserSession.class, HttpServletRequest.class, HttpServletResponse.class,
                        HttpSession.class)
//              .select().apis(RequestHandlerSelectors.basePackage("com.asiainfo.aigov.fdapp.web.controller"))//指定目录
                .select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//方法必须有ApiOperation注解
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("家庭医生接口文档").build();
    }
    
}

使用注解

package com.asiainfo.aigov.fdapp.web.controller;

import javax.servlet.http.HttpServletRequest;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import com.alibaba.fastjson.JSONObject;
import com.asiainfo.aigov.Constants;
import com.asiainfo.aigov.familydoctor.model.FdAppoint;
import com.asiainfo.aigov.fdapp.service.AppointService;
import com.asiainfo.aigov.system.model.SysUser;
import com.asiainfo.aigov.system.web.session.UserSession;
import com.asiainfo.frame.annotation.AppUser;
import com.asiainfo.frame.annotation.Remarks;
import com.asiainfo.frame.model.AjaxResponse;
import com.asiainfo.frame.model.PagedList;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(tags = {"预约接口"})
@Controller
@RequestMapping("/app/doc/apm")
public class AppointController {
    @Autowired
    private AppointService sv;

    @ApiOperation(value="查询预约",httpMethod="POST")
    @ApiImplicitParams({
        @ApiImplicitParam(name="pageCount", value="每页数目", required=true),
        @ApiImplicitParam(name="curPageNum", value="当前页码", required=true),
        @ApiImplicitParam(name="extraCon", value="额外查询条件", required=false)
    })
    @RequestMapping("/getList")
    @ResponseBody
    @Remarks("查询预约")
    public AjaxResponse getList(@AppUser(Constants.FDAPP_INFO_KEY) UserSession userSession,  String pageCount, String curPageNum, String extraCon,
            HttpServletRequest request) throws Exception {
        SysUser user = (SysUser) userSession.getUser();
        PagedList<JSONObject> list = sv.getList(pageCount,curPageNum,user.getId(),extraCon);
        AjaxResponse resp = new AjaxResponse();
        resp.setData(list);
        return resp;
    }

整个实体作为参数

其中参数类型为数值型的，如age(类型为BigDecimal)，要增加example="0"，否则生成文档的时候会报错。

package com.asiainfo.aigov.familydoctor.model;

import java.math.BigDecimal;

import com.asiainfo.aigov.system.model.SysUser;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel
public class FdUser extends SysUser {
    /**
     * This field was generated by MyBatis Generator.
     * This field corresponds to the database column FD_USER.ID
     *
     * @mbggenerated Fri Jun 22 10:59:06 CST 2018
     */
    @ApiModelProperty("主键标识")
    private String id;

    /**
     * This field was generated by MyBatis Generator.
     * This field corresponds to the database column FD_USER.NAME
     *
     * @mbggenerated Fri Jun 22 10:59:06 CST 2018
     */
    @ApiModelProperty("姓名")
    private String name;

    /**
     * This field was generated by MyBatis Generator.
     * This field corresponds to the database column FD_USER.CARD_NUM
     *
     * @mbggenerated Fri Jun 22 10:59:06 CST 2018
     */
    @ApiModelProperty("身份证号")
    private String cardNum;

    /**
     * This field was generated by MyBatis Generator.
     * This field corresponds to the database column FD_USER.SEX
     *
     * @mbggenerated Fri Jun 22 10:59:06 CST 2018
     */
    @ApiModelProperty("性别")
    private String sex;

    /**
     * This field was generated by MyBatis Generator.
     * This field corresponds to the database column FD_USER.AGE
     *
     * @mbggenerated Fri Jun 22 10:59:06 CST 2018
     */
    @ApiModelProperty(value="年龄", example="0")
    private BigDecimal age;

效果

访问http://localhost:8080/familydoctor-webapp/swagger-ui.html，可以在线进行接口的调试，相当的方便。

接口文档

结后语

略