文档章节

使用Swagger整合SpringMVC自动生成Restful接口文档

sluggarddd
 sluggarddd
发布于 2016/07/28 14:40
字数 731
阅读 503
收藏 2

相信这一篇《Restful形式接口文档生成之Swagger与SpringMVC整合手记》大家都已经看过了。

根据这一篇blog搭建而出的是Swagger1.2的服务。现在最新的swagger-ui的validator已经通不过了。所以费了点劲升级到2.0,顺便记录一下。

 

相比于1.2,2.0的集成要简单不少。

MAVEN依赖

 <!-- 生成api文档-->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>${springfox.swagger2.version}</version>
</dependency>

有一点需要注意的是,springfox-swagger2是依赖springframework的webmvc、web、context的,需要注意自己使用的版本 ,避免造成版本间的冲突,从而在中央库中寻找合适的springfox版本。

案例:一开始我用的版本是springfox 2.1.2,spring版本是4.2.5,然而springfox 2.1.2使用了spring 4.0.1里面的api。4.2.5是没有的,所以一直启动失败,切换至最新的2.5.1之后表现正常。

 

简单配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
//                .paths(PathSelectors.regex("/*"))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "标题",
                "描述",
                "版本号",
                "API TOS",
                new Contact("邮箱地址", "", ""),
                "API License",
                "API License URL"
        );

    }
}

其中Docket里面还有许多自定义的设置可以配置,这里就不赘述的,可以参考官网文档

简单试用

@Api(tags = {"我是分类名"}, description = "我是描述")
@RestController
@RequestMapping("/swaggertest")
public class TestController {

    @ApiOperation("我是接口")
    @RequestMapping(value = "/test", method = RequestMethod.GET)
    public void test(@ApiParam(name = "用户id") @RequestParam("uid") String uid) {

    }
}

常用的三个annotation@APi、@ApiOperation、@ApiParam就可以满足百分之90的需求了。我在上面写了标注性质的描述,可以对照下面的图片看。

值得一提的是,他可以自动识别springmvc的annotation如RequestMapping,RequestParam,这倒是省事不少。

效果如下:

这时候运行你的web程序,访问http://{host}:{port}/{projectRoot}/v2/api-docs

就可以看到一长串定义的json。这就是用于swagger-ui展示的玩意儿。

 

 

接下来就是swagger-ui的部署了

如果你想在原项目中集成。

1、将swagger-ui从github上clone下来 https://github.com/swagger-api/swagger-ui

2、将其dist目录下的所有文件拷贝到自己webapp/swagger下

3、在spring配置文件中加上下面这句,使其html可以直接访问

<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

4、访问http://{host}:{port}/{projectRoot}/swagger/index.html

5、在搜索栏搜索上面提到的提供json的地址即可

 

如果swagger-ui另外部署

1、你可以直接按照github上的教程使用node,跑起来

2、如果你不会node或者不想用,用你springmvc的经验搭建一个空项目把刚刚dist的东西丢进去,让其能直接访问/dist/index.html。

3、在搜索栏查看你想知道restapi文档的服务

4、会发现对方因为cors拒绝访问

5、需要在对方的web.xml中加入


    <!-- 发布记得删除-->

    <filter>
        <filter-name>CorsFilter</filter-name>
        <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>CorsFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

 

© 著作权归作者所有

sluggarddd
粉丝 7
博文 14
码字总数 11821
作品 0
程序员
私信 提问
Restful形式接口文档生成之Swagger与SpringMVC整合手记

文章转载地址:http://javatech.wang/index.php/archives/74/ 笔者目前正在搭建一套API服务框架,考虑到客户端能够更方便的调用API服务(这里说的更方便是指避免不厌其烦地解说各接口需要的参...

北极之北
2016/04/01
13.2K
8
smart-doc 1.7.0 重磅发布,Java 零注解文档生成工具

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。 smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解...

上官胡闹
10/08
2.1K
4
SpringBoot接口文档自动生成

由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业...

chcvn
2018/04/10
0
0
SpringBoot整合Swagger2实践

版权声明:本文为博主原创文章,欢迎大家讨论,未经博主允许不得转载. https://blog.csdn.net/u010398771/article/details/88944880 关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工...

长河
04/01
0
0
smart-doc 1.6.4 发布,Java 零注解文档生成工具

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解侵...

上官胡闹
09/22
1K
1

没有更多内容

加载失败,请刷新页面

加载更多

Mybatis Plus删除

/** @author beth @data 2019-10-17 00:30 */ @RunWith(SpringRunner.class) @SpringBootTest public class DeleteTest { @Autowired private UserInfoMapper userInfoMapper; /** 根据id删除......

一个yuanbeth
今天
4
0
总结

一、设计模式 简单工厂:一个简单而且比较杂的工厂,可以创建任何对象给你 复杂工厂:先创建一种基础类型的工厂接口,然后各自集成实现这个接口,但是每个工厂都是这个基础类的扩展分类,spr...

BobwithB
今天
5
0
java内存模型

前言 Java作为一种面向对象的,跨平台语言,其对象、内存等一直是比较难的知识点。而且很多概念的名称看起来又那么相似,很多人会傻傻分不清楚。比如本文我们要讨论的JVM内存结构、Java内存模...

ls_cherish
今天
4
0
友元函数强制转换

友元函数强制转换 p522

天王盖地虎626
昨天
5
0
js中实现页面跳转(返回前一页、后一页)

本文转载于:专业的前端网站➸js中实现页面跳转(返回前一页、后一页) 一:JS 重载页面,本地刷新,返回上一页 复制代码代码如下: <a href="javascript:history.go(-1)">返回上一页</a> <a h...

前端老手
昨天
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部