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

2018-10-10|来源:

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


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

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就出现前面那个页面效果了

相关问答

更多

swagger ui怎么进行在线测试

Web API文档工具列表 Swagger ——Swagger框架可以通过代码生成漂亮的在线API,甚至可以提供运行示例。支持Scala、Java、Javascript、Ruby、PHP甚至 Actionscript 3。在线 Demo 。 I/O Docs ——I/O Docs是一个用于RESTful Web APIs的交互式文档系统...

如何在.net中使用Swagger-UI

Swagger-UI纯碎的基于html+javascript实现,在.NET中应用,也就是在 asp.net 页面中应用相应的 js,按照规范写 html 就可以了。 有一个Swagger.Net.UI 你可以搜索一下。

swagger ui怎么进行测试表中文

Xcode 7 引入了用户界面测试,旨在确保您在代码中所做的修改,不会向您的用户呈现出乎意料的效果。 Wil Turner 和 Brooke Callahan 在第 406 节展示了新框架,Xcode 中的 UI 测试。演示了一个简单的任务管理应用,对工具中的一些 API 和功能进行。   曾经有一段时间,人们习惯于在MS Excel里面编写单元测试用例,然后开发人员就按照单元测试用例一步一步的来实现用例。   这通常是很耗时的漫长的过程,尤其是如果应用很大或者UI很复杂的话。 这一套单元测试的执 ...

swagger 怎么整合springmvc 文档

groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> <exclusions> <exclusion> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> </exclusion> <exclusion> <groupId>o ...

怎样使用python对swagger api 文档进行测试

Swagger-UI简单而一目了然。它能够纯碎的基于html+javascript实现,只要稍微整合一下便能成为方便的API在线测试工具。项目的设计架构中一直提倡使用TDD(测试驱动)原则来开发,swagger-ui在这方面更是能提供很大帮助。 Swagger-UI更倾向于在线测试接口和数据,但其核心是一个javascript插件,只要稍作修改,便能按需求定制出不同格式的说明文档,在github上更是基于它集成到各种语言环境,分支众多。

相关文章

更多

最近更新

更多