[Java知识库]微服务接口通过swagger实现接口文档自动在线生成

对于需要提供接口给第三方访问的平台，有一个完整、准确的接口文档，是很有帮助的。由于业务增加或者变更，经常需要对接口进行更新维护，单独的接口文档维护常常不能及时保持与实际接口变更同步，导致看到的接口文档是过时和不准确。

swagger通过在接口中增加相关的注解，由swagger根据注解中的内容自动生成接口文档，在开发接口的同时，就完成了接口文档的编写，最后由swagger根据代码中的注解生成标准格式的在线接口文档。此外，还可以在线对接口进行测试。

1. 添加依赖

<!-- swagger2-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>


<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-annotations</artifactId>
	<version>1.5.21</version>
</dependency>

<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-models</artifactId>
	<version>1.5.21</version>
</dependency>

<!-- swagger2-UI-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 添加资源拦截器

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class ResourcesConfig implements WebMvcConfigurer
{
            
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry)
    {
        
        /** swagger配置 */
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    
}

3. 接口添加注解

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;

@Api("支付接口说明")
@RestController
@RequestMapping("/pay")
public class PayController extends BaseController
{

	@ApiOperation("支付请求")    
    @PostMapping("/payorder")
    @RepeatSubmit
    public AjaxResult payorder(OrderEntity order)
    {
        if (StringUtils.isNull(order) || StringUtils.isNull(order.getOrderId()))
        {
            return error("用户ID不能为空");
        }
        return AjaxResult.success(1);
    }
}

4. 参数定义

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

@ApiModel("订单实体")
class OrderEntity
{
    @ApiModelProperty("订单ID")
    private Integer orderId;

    @ApiModelProperty("商户编号")
    private String merchantNo;

    @ApiModelProperty("订单编号")
    private String orderNo;

    @ApiModelProperty("商品名称")
    private String productName;

	public Integer getOrderId() {
		return orderId;
	}

	public void setOrderId(Integer orderId) {
		this.orderId = orderId;
	}

	public String getMerchantNo() {
		return merchantNo;
	}

	public void setMerchantNo(String merchantNo) {
		this.merchantNo = merchantNo;
	}

	public String getOrderNo() {
		return orderNo;
	}

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

	public String getProductName() {
		return productName;
	}

	public void setProductName(String productName) {
		this.productName = productName;
	}   
    
}

5. swagger基本配置

@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("支付平台")
                // 描述
                .description("用于支付平台接口相关信息..")
                // 作者信息
                .contact(new Contact(Global.getName(), null, null))
                // 版本
                .version("版本号:" + Global.getVersion())
                .build();
    }
}

6. 通过页面访问

?接口在线测试：

?可以看到，在接口中添加到注解的说明信息，都显示在页面上了。根据代码中的注解说明，很方便知道参数的含义。