spring cloud 学习(10) - 利用springfox集成swagger

对绝大多数程序员而言，写接口文档是一件痛苦的事情，相对文档，他们更愿意写代码。最理想的情况就是：代码即文档！服务开发完成后，部署上去文档就自动生成，没错，这就是springfox + swagger要解决的问题！

swagger号称 THE WORLD'S MOST POPULAR API TOOLING。但swagger默认情况下，仍要单独部署，程序员还是要跑到一个单独的web页面上编辑，写一堆yaml文档，依然不爽。

github上有一个springfox项目，可以在开发rest服务时，只要加一些注解，就自动生成swagger-ui界面，以及相关的文档，而且可以跟spring-boot/spring-cloud无缝集成。

步骤：

一、添加依赖项

    dependencies {
        ...
        compile "io.springfox:springfox-swagger2:2.7.0"
        compile "io.springfox:springfox-swagger-ui:2.7.0"
        ...
    }

　　

二、添加swagger配置类

package cn.mwee.order.cloud.service.express.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by yangjunming on 13/10/2017.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("xxx.controller")) //Controller所在的package
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public WebMvcConfigurerAdapter addResourceHandlers() {
        return new WebMvcConfigurerAdapter() {
            @Override
            public void addResourceHandlers(ResourceHandlerRegistry registry) {
                registry.addResourceHandler("swagger-ui.html")
                        .addResourceLocations("classpath:/META-INF/resources/");
                registry.addResourceHandler("/webjars/**")
                        .addResourceLocations("classpath:/META-INF/resources/webjars/");
            }
        };
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("express-service online api document")
                .description("某某服务") 
                .contact(new Contact("作者名字", "http://作者介绍网址", "作者@邮箱.com"))
                .version("1.0.0") //显示版本号
                .build();
    }
}

 

三、在Controller上添加注解

package cn.mwee.order.cloud.service.express.controller;

import cn.mwee.order.cloud.admin.common.controller.AbstractController;
import cn.mwee.order.cloud.admin.service.dto.common.DataResult;
import cn.mwee.order.cloud.admin.service.dto.express.sf.*;
import cn.mwee.order.cloud.admin.service.express.SFExpressService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

/**
 * Created by 菩提树下的杨过(http://yjmyzz.cnblogs.com/) on 2017/7/18.
 */
@RestController
@RefreshScope
@RequestMapping("/sf")
@Api(consumes = "application/json",
        produces = "application/json",
        protocols = "http",
        basePath = "/sf", value = "顺丰对接服务")
public class SFController extends AbstractController {

    ...

    @ApiOperation(value = "下单", tags = "顺丰速运")
    @PostMapping(value = "submitOrder")
    public DataResult<SFSubmitResponse> submitOrder(@RequestBody SFSubmitOrderRequest request) throws Exception {
        return ...;
    }

    ...

}

注意上面几处带@Api开头的注解

 

四、参数实体上添加注解

package cn.mwee.order.cloud.admin.service.dto.express.sf;

import cn.mwee.order.cloud.admin.service.dto.express.ExpressBaseOrder;
import cn.mwee.order.common.utils.date.DateUtil;
import com.alibaba.fastjson.annotation.JSONField;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;

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

/**
 * 顺丰的物流订单
 * Created by 菩提树下的杨过(http://yjmyzz.cnblogs.com/) on 26/09/2017.
 */
@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(description = "顺丰-提交订单参数")
public class SFSubmitOrderRequest extends ExpressBaseOrder {

    @ApiModelProperty(value = "商家编码(顺丰分配提供)", required = true, dataType = "String", example = "A001")
    private String clientCode; //商家编码，为顺丰分配提供

    ...
}

还是注意上面几处带@Api开头的注解，一看就懂。

 

启动后，就可以用 http://xxxx.xxxx:port/swagger-ui.html访问了

随便点开一个方法，比如cancelOrder

还可以直接调用REST(相当于postman之类的rest服务测试工具了）