对绝大多数程序员而言,写接口文档是一件痛苦的事情,相对文档,他们更愿意写代码。最理想的情况就是:代码即文档!服务开发完成后,部署上去文档就自动生成,没错,这就是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配置类
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
1 package cn.mwee.order.cloud.service.express.config; 2 3 import org.springframework.context.annotation.Bean; 4 import org.springframework.context.annotation.Configuration; 5 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; 6 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; 7 import springfox.documentation.builders.ApiInfoBuilder; 8 import springfox.documentation.builders.PathSelectors; 9 import springfox.documentation.builders.RequestHandlerSelectors; 10 import springfox.documentation.service.ApiInfo; 11 import springfox.documentation.service.Contact; 12 import springfox.documentation.spi.DocumentationType; 13 import springfox.documentation.spring.web.plugins.Docket; 14 import springfox.documentation.swagger2.annotations.EnableSwagger2; 15 16 /** 17 * Created by yangjunming on 13/10/2017. 18 */ 19 @Configuration 20 @EnableSwagger2 21 public class SwaggerConfig { 22 23 @Bean 24 public Docket createRestApi() { 25 return new Docket(DocumentationType.SWAGGER_2) 26 .apiInfo(apiInfo()) 27 .select() 28 .apis(RequestHandlerSelectors.basePackage("xxx.controller")) //Controller所在的package 29 .paths(PathSelectors.any()) 30 .build(); 31 } 32 33 @Bean 34 public WebMvcConfigurerAdapter addResourceHandlers() { 35 return new WebMvcConfigurerAdapter() { 36 @Override 37 public void addResourceHandlers(ResourceHandlerRegistry registry) { 38 registry.addResourceHandler("swagger-ui.html") 39 .addResourceLocations("classpath:/META-INF/resources/"); 40 registry.addResourceHandler("/webjars/**") 41 .addResourceLocations("classpath:/META-INF/resources/webjars/"); 42 } 43 }; 44 } 45 46 private ApiInfo apiInfo() { 47 return new ApiInfoBuilder() 48 .title("express-service online api document") 49 .description("某某服务") 50 .contact(new Contact("作者名字", "http://作者介绍网址", "作者@邮箱.com")) 51 .version("1.0.0") //显示版本号 52 .build(); 53 } 54 }
三、在Controller上添加注解
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
1 package cn.mwee.order.cloud.service.express.controller; 2 3 import cn.mwee.order.cloud.admin.common.controller.AbstractController; 4 import cn.mwee.order.cloud.admin.service.dto.common.DataResult; 5 import cn.mwee.order.cloud.admin.service.dto.express.sf.*; 6 import cn.mwee.order.cloud.admin.service.express.SFExpressService; 7 import io.swagger.annotations.Api; 8 import io.swagger.annotations.ApiOperation; 9 import org.springframework.beans.factory.annotation.Autowired; 10 import org.springframework.cloud.context.config.annotation.RefreshScope; 11 import org.springframework.web.bind.annotation.PostMapping; 12 import org.springframework.web.bind.annotation.RequestBody; 13 import org.springframework.web.bind.annotation.RequestMapping; 14 import org.springframework.web.bind.annotation.RestController; 15 16 import javax.servlet.http.HttpServletRequest; 17 18 /** 19 * Created by 菩提树下的杨过(http://yjmyzz.cnblogs.com/) on 2017/7/18. 20 */ 21 @RestController 22 @RefreshScope 23 @RequestMapping("/sf") 24 @Api(consumes = "application/json", 25 produces = "application/json", 26 protocols = "http", 27 basePath = "/sf", value = "顺丰对接服务") 28 public class SFController extends AbstractController { 29 30 ... 31 32 @ApiOperation(value = "下单", tags = "顺丰速运") 33 @PostMapping(value = "submitOrder") 34 public DataResult<SFSubmitResponse> submitOrder(@RequestBody SFSubmitOrderRequest request) throws Exception { 35 return ...; 36 } 37 38 ... 39 40 }
注意上面几处带@Api开头的注解
四、参数实体上添加注解
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
1 package cn.mwee.order.cloud.admin.service.dto.express.sf; 2 3 import cn.mwee.order.cloud.admin.service.dto.express.ExpressBaseOrder; 4 import cn.mwee.order.common.utils.date.DateUtil; 5 import com.alibaba.fastjson.annotation.JSONField; 6 import io.swagger.annotations.ApiModel; 7 import io.swagger.annotations.ApiModelProperty; 8 import lombok.Data; 9 import lombok.EqualsAndHashCode; 10 11 import java.util.ArrayList; 12 import java.util.Date; 13 import java.util.List; 14 15 /** 16 * 顺丰的物流订单 17 * Created by 菩提树下的杨过(http://yjmyzz.cnblogs.com/) on 26/09/2017. 18 */ 19 @Data 20 @EqualsAndHashCode(callSuper = false) 21 @ApiModel(description = "顺丰-提交订单参数") 22 public class SFSubmitOrderRequest extends ExpressBaseOrder { 23 24 @ApiModelProperty(value = "商家编码(顺丰分配提供)", required = true, dataType = "String", example = "A001") 25 private String clientCode; //商家编码,为顺丰分配提供 26 27 ... 28 }
还是注意上面几处带@Api开头的注解,一看就懂。
启动后,就可以用 http://xxxx.xxxx:port/swagger-ui.html访问了
随便点开一个方法,比如cancelOrder
还可以直接调用REST(相当于postman之类的rest服务测试工具了)