使用 SwaggerUI 生成接口文档（配示例）

在项目开发中，接口文档一直是个头疼的问题。本来项目开发时间就紧张，还需要另外写文档给调用方看，但是不写又不行，无法沟通，写了还要随着项目迭代一直更新，费时费力。

那有没有工具能够识别我们的代码自动生成接口文档呢？答案是有的。这篇文章就介绍市面上常用的接口文档生成框架：Swagger-UI 的简单使用。

讲 Swagger-UI 前需先了解下 Swagger，https://swagger.io/，Swagger 是一个常用的接口工具。

官方给自己的定义是：THE WORLD’S MOST POPULAR API TOOLING。

Swagger-UI 只是其中的一块，主要是通过代码里的注解，生成在线的接口文档界面，以便沟通。

除了 Swagger-UI，Swagger 还有 Swagger Editor（在线编辑接口文档）和 Swagger Codegen（根据接口文档生成代码，可以生成各种语言的代码，厉害吧！）。

先看效果

首先来两张高清大图，看看生成的效果。

生成效果

整合接入步骤

（以一个普通的 SpringMVC 项目为例）

加入必须的依赖包（maven）

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

代码方式添加相关配置

package com.zhangzw.swagger.spring;

import io.swagger.annotations.ApiOperation;

import java.util.ArrayList;
import java.util.List;

import javax.servlet.http.HttpServletResponse;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@ComponentScan("com.zhangzw.swagger")
@EnableWebMvc
@EnableSwagger2
public class SpringConfiguration extends WebMvcConfigurerAdapter {
        
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        super.addResourceHandlers(registry);
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/swagger/");
    }

    @Bean
    public Docket docket() {
        List<ResponseMessage> responseMessages = new ArrayList<ResponseMessage>();
        responseMessages.add(new ResponseMessageBuilder().code(HttpServletResponse.SC_OK).message("操作成功").build());
        responseMessages.add(new ResponseMessageBuilder().code(HttpServletResponse.SC_NOT_FOUND).message("资源不存在").build());
        responseMessages.add(new ResponseMessageBuilder().code(HttpServletResponse.SC_INTERNAL_SERVER_ERROR).message("服务器异常").build());
        
        return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .useDefaultResponseMessages(false)
                    .globalResponseMessage(RequestMethod.GET, responseMessages)
                    .globalResponseMessage(RequestMethod.POST, responseMessages)
                    .globalResponseMessage(RequestMethod.DELETE, responseMessages)
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("测试项目").version("1.0.0").description("这是项目描述").build();
    }
}

修改 Controller 接口

package com.zhangzw.swagger.web;

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

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@Api(tags="订单模块") // Swagger-UI 描述在类上面，可以做分组。
public class OrderController {

    @RequestMapping(method = RequestMethod.GET, value = "/order/orderInfo/{orderId:.+}")
    @ResponseBody
    @ApiOperation(value = "获取订单") // 让 Swagger-UI 解析这个接口。
    public OrderInfo getOrderInfo(String orderId) {
        return new OrderInfo();
    }
    
    @RequestMapping(method = RequestMethod.DELETE, value = "/order/delOrder.do")
    @ResponseBody
    @ApiOperation(value = "删除订单")
    public BaseResponse delOrder(String orderId) {
        return new BaseResponse();
    }
    
    @RequestMapping(method = RequestMethod.POST, value = "/order/queryOrderList.do")
    @ResponseBody
    @ApiOperation(value = "查询订单列表")
    public QueryOrderListResponse getOrderInfo(@RequestBody QueryOrderListRequest req) {
        return new QueryOrderListResponse();
    }
}

如果接口使用 DTO 接收和返回数据，可以在 DTO 上加入注解，如：

package com.zhangzw.swagger.web;

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

import java.util.Date;

@ApiModel(description = "订单实体")
public class OrderInfo {

    @ApiModelProperty(value = "订单号", example = "201701011234", notes = "订单的编号")
    private String orderNo;
    
    @ApiModelProperty("创建时间")
    private Date createTime;
    
    @ApiModelProperty("中介公司编码")
    private String agencyCode;

    @ApiModelProperty("中介公司名称")
    private String agencyName;

    @ApiModelProperty("门店 ID")
    private String storeId;

    @ApiModelProperty("门店名称")
    private String storeName;

    public String getOrderNo() {
        return orderNo;
    }

    public void setOrderNo(String orderNo) {
        this.orderNo = orderNo;
    }

    public Date getCreateTime() {
        return createTime;
    }

    public void setCreateTime(Date createTime) {
        this.createTime = createTime;
    }

    public String getAgencyCode() {
        return agencyCode;
    }

    public void setAgencyCode(String agencyCode) {
        this.agencyCode = agencyCode;
    }

    public String getAgencyName() {
        return agencyName;
    }

    public void setAgencyName(String agencyName) {
        this.agencyName = agencyName;
    }

    public String getStoreId() {
        return storeId;
    }

    public void setStoreId(String storeId) {
        this.storeId = storeId;
    }

    public String getStoreName() {
        return storeName;
    }

    public void setStoreName(String storeName) {
        this.storeName = storeName;
    }

}

结束

这样就可以了，是不是很简单？只需要加入一些注解，文档就生成了，对代码侵入很小，保证了文档与代码的同步，最重要的是效率高啊！^_^

写写代码，做做架构