首页 > 编程开发 > java教程网 > java教程

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

2016-10-10 23:20:45| 发布: | 浏览: 3476

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


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

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

如非特别注明,本站内容均为领悟书生原创,转载请务必注明作者和原始出处。
本文地址:http://www.656463.com/javajiaocheng/FV3Yzm.htm

相关专题

  • dubbo教程

    dubbo教程

    DUBBO是一个分布式服务框架,致力于提供高性能和透明化的RPC远程服务调用方案,是阿里巴巴SOA服务化治理方案的核心框架,本教程带你入门学习dubbo框架的相关知识

  • RabbitMQ 教程

    RabbitMQ 教程

    RabbitMQ是一个开源的,在AMQP基础上完整的,可复用的企业消息系统。支持主流的操作系统,Linux、Windows、MacOX等。多种开发语言支持,Java、Python、Ruby、.NET、PHP、C/C++、node.js等。本教程带你学习RabbitMQ环境搭建、RabbitMQ简单队列、work队列、发布订阅消息、各种Exchange应用、与spring整合等

  • java8新特征详解

    java8新特征详解

    本教程详细讲解Java8的新特新,结合简单的示例代码来讲解如何使用默认接口方法,lambda表达式,方法引用以及多重Annotation,同时你将会学到JAVA8最新的API上的改进,比如流,函数式接口,Map以及全新的日期API

  • WebSocket教程

    WebSocket教程

    WebSocket 规范的目标是在浏览器中实现和服务器端双向通信.双向通信可以拓展浏览器上的应用类型,例如实时的数据推送(股票行情),游戏,聊天/im 等.本教程通过java简单的示例带你快速学会WebSocket编程

  • json教程

    json教程

    JSON 即 JavaScript Object Natation,它是一种轻量级的数据交换格式,非常适合于服务器与 JavaScript 的交互。本专题详细讲解json、jackson、fastjson等工具包的操作教程

  • junit教程

    junit教程

    junit基本介绍,hamcrest和testSuite介绍,基于测试开发讲解和cobertura框架介绍,stub和mock简介,dbunit的使用,dbunit实际运用,easymock的使用,easymock的实际应用,利用easymock测试简单的servlet,cactus的使用,基于Jetty的cactus的使用

  • java教程

    java教程

    java在线教程汇集业界最好的java教程资料,提供最好的学习Java资源,是国内一流的java资料平台

  • i18n 国际化

    i18n 国际化

    国际化(internationalization)又称为 i18n(读法为i 18 n,据说是因为internationalization(国际化)这个单词从i到n之间有18个英文字母,i18n的名字由此而来)

  • freemarker教程

    freemarker教程

    freemarker是现在企业中用得最多的模板引擎,可以根据模板生成相当的静态页面等

  • jstl el 教程

    jstl el 教程

    JSTL指的是JavaServer Pages标准标记库,是封装了许多JSP应用程序通用的核心功能的JSP标签的集合,包括核心标签(Core Tags),格式化标签(Formatting tags),SQL标签(SQL tags),XML标签(XML tags),JSTL函数(JSTL Functions)

  • Struts2教程

    Struts2教程

    Struts2,Struts2教程,Struts2学习,Struts2实例,Struts2视频教程

  • Hibernate教程

    Hibernate教程

    Hibernate,Hibernate教程,Hibernate学习,Hibernate实例,Hibernate视频教程

  • spring教程

    spring教程

    spring,spring教程,spring学习,spring实例,spring视频教程

  • java视频教程

    java视频教程

    java,视频教程,java视频教程,java web 视频教程,java基础视频教程

  • java文件操作专题教程

    java文件操作专题教程

    java创建文件、java创建目录、java读写文件,java读取大文件,java文件操作示例

  • java压缩与解压专题教程

    java压缩与解压专题教程

    java压缩教程,java解压,java压缩文件,java压缩目录