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

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

阅读量：6509 次

发布时间：2019-06-24

本文共 5274 字，大约阅读时间需要 17 分钟。

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

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

github上有一个项目，可以在开发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配置类

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 @Configuration20 @EnableSwagger221 public class SwaggerConfig {22 23     @Bean24     public Docket createRestApi() {25         return new Docket(DocumentationType.SWAGGER_2)26                 .apiInfo(apiInfo())27                 .select()28                 .apis(RequestHandlerSelectors.basePackage("xxx.controller")) //Controller所在的package29                 .paths(PathSelectors.any())30                 .build();31     }32 33     @Bean34     public WebMvcConfigurerAdapter addResourceHandlers() {35         return new WebMvcConfigurerAdapter() {36             @Override37             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 }

View Code

三、在Controller上添加注解

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 @RestController22 @RefreshScope23 @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
      
        submitOrder(@RequestBody SFSubmitOrderRequest request) throws Exception {35         return ...;36     }37 38     ...39 40 }

View Code

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

四、参数实体上添加注解

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 @Data20 @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 }

View Code

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

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

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

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

转载地址：http://mcbfo.baihongyu.com/

你可能感兴趣的文章