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

2019-03-10 23:20|来源: 网路

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


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

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

相关问答

更多

TypeError:p.easing [this.easing]不是一个函数(TypeError: p.easing[this.easing] is not a function)

您需要为扩展的缓存选项包含jQueryUI。 我认为可能有一个选择,只包括下载缓存,或至少只是基础库加宽松。 You need to include jQueryUI for the extended easing options. I think there may be an option to only include the easing in the download, or at least just the base library plus easing.

Spring MVC vs JSF [duplicate](Spring MVC vs JSF [duplicate])

当然,每个人都会有所不同,但是我建议Spring MVC,因为它是一个基于请求的框架,如Struts。 当然,你会想知道关于核心Spring的东西,如反转控制/依赖注入(但我会考虑一个加号),以及你将要用于数据库访问的任何东西(只是JDBC?Hibernate? iBatis?等)。 JSF是基于组件的,这是基于请求的框架的一个不同的范例。 如果你打算去JSF路线,我建议从JBoss看Seam。 更多的是使用JSF作为Web / Presentation端点和EJB作为后端的前端框架。 几乎所有

使用Homebrew更新OS X上的OpenSSL(Update OpenSSL on OS X with Homebrew)

如果你使用Homebrew / usr / local / bin应该已经在$PATH的前面,或至少在/ usr / bin之前。 如果您现在在终端窗口中运行brew link --force openssl ,请打开一个新的,并在which openssl运行which openssl 。 现在应该在/ usr / local / bin下显示openssl 。 If you're using Homebrew /usr/local/bin should already be at the f

如何检查连接字符串是否有效?(How to check if connection string is valid?)

你可以尝试连接? 对于快速(离线)验证,也许使用DbConnectionStringBuilder解析它... DbConnectionStringBuilder csb = new DbConnectionStringBuilder(); csb.ConnectionString = "rubb ish"; // throws 但是要检查db是否存在,您需要尝试连接。 当然,如果你知道提供者最简单的话: using(SqlConnection conn = new S

在哪里可以下载Java EE 6教程示例?(Where can I download Java EE 6 Tutorial Examples? [closed])

我也看不到更新工具中的教程文件。 shurik2533提供的下载链接是JavaEE5的教程文件,而不是JavaEE6。 使用John做的,我使用以下方式从svn存储库下载文件: $ svn export https://svn.java.net/svn/javaeetutorial~svn JavaEE6tutorial/ 仅下载示例: $ svn export https://svn.java.net/svn/javaeetutorial~svn/branches/javaee-tutori

相关文章

更多

最近更新

更多