java教程

java基础教程,java视频教程,java pdf电子书下载,java免费视频教程,java视频教程下载

Swagger UI 快速入门-springmvc 整合Swagger UI 教程

2016-10-10| 发布: | 浏览: 5141 |保存PDF

现在很多开发团队都是前端开发与服务端分离,前端直接调用服务端写好接口。


如果你是服务端开发人员,也许你要做以下工作:

1、写接口文档,描述每个接口的功能,请求参数和返回结果
2、要自测自己所写的接口


解决上面两个问题,也许你之前的做法是

1、建一个wiki平台或文档,让前端自己去查看
2、使用单元测试或postman测试


有了Swagger UI ,会让你从中解放出来,在写代码的时候,就顺便把上面的事情给解决了

Swagger UI一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档
先来看下面几张效果图


是不是和postman有点像,是不是方法的描述、请求参数、返回值都有了。这都是怎么做到的?


官方第一手资料:
Swagger UI 官网: http://swagger.io/swagger-ui/
Swagger UI 源码地址: https://github.com/swagger-api/swagger-ui


由于项目中使用的是springmvc,所以只测试了Swagger UI结合springmvc的例子
先添加maven依赖,spring其他依赖在这里就不做多说
<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.2</version>
</dependency>


Swagger整合spring的配置类,此类会注入SpringSwaggerConfig,并配置Swagger拦截的路径、页面展示的信息等
package com._656463.swagger;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
 
@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan("com._656463.biz.*.controller")
public class ApiSwaggerConfig {
    private SpringSwaggerConfig springSwaggerConfig;
 
    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }
 
    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");
    }
 
    private ApiInfo apiInfo(){
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title", //页面的标题
                "My Apps API Description",
                "My Apps API terms of service", 
                "My Apps API Contact Email", 
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}


在spring配置文件中,声明这个bean,让其初始化(因为ApiSwaggerConfig我是放在一个特殊的包中,上线后直接去掉这个bean配置,让其不能被访问)
<bean class="com._656463.swagger.ApiSwaggerConfig" />


在controller中使用swagger ui
package com._656463.biz.web.controller.datatransfer;
 
import javax.annotation.Resource;
 
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
 
.......
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
 
@Controller
@RequestMapping("/datatransfer")
public class DataTransferController {
     
    @Resource
    private DataTransferFacade transferFacade;
     
    @ApiOperation(value = "根据订单ID同步数据", httpMethod = "GET", response = ResponseDto.class, notes = "syncByOrderId")
    @RequestMapping(value = "syncByOrderId", method = RequestMethod.GET)
    @ResponseBody
    public ResponseDto syncByOrderId(@ApiParam(required = true, name="orderId", value = "订单ID")  @RequestParam String orderId,Integer type) {
        。。。。。。
    }
}

@ApiOperation是配置该的一些信息,方便在页面展示,还有请求方式等

@ApiParam 是对参数的一些描述



在页面怎么展示呢,这是需要页面的,页面直接在Swagger UI 的github上下载最新的源码,然后把dist下面的所有文件拷贝到你的项目中,当然也可以放在其他能访问的web项目里。


例如我拷贝到我项目的webapp/docapi下


项目启动后,Swagger UI的访问地址是http://ip:host[/项目]/api-docs,所以把下载下来的url改为你项目的,然后请求回json数据让其前端代码解析


到此,就全部配置完毕

访问http://localhost:8067/docsapi/index.html就出现前面那个页面效果了

大家都在看

热门访问