文档章节

精通Spring Boot——第九篇:整合Swagger在线文档

liululee
 liululee
发布于 2018/10/14 21:44
字数 1572
阅读 198
收藏 30

开发中最烦的一件事是什么?当你全心全意思考的时候,前端笑眯眯的过来了:“大哥,你没告诉我该传什么参数!”......然后一堆吧啦吧啦扯淡,好了,前端大佬心满意足的走了,你以为事情也就这么结束了。滴滴滴,微信消息来了:“接口怎么不通啊,你是不是代码写的有问题啊?”一顿操作后,登上控制台,日志一看。啊~(我们一起学土拨鼠叫)内心是崩溃的... 参数少了,参数类型不对,格式不对,各种。这时候很想丢个文档给前端:你自己看吧!然而,写文档真的太麻烦了,懒...只好去逛逛论坛,百度谷歌下有没有什么生成在线文档的工具了,结果如你所愿,还真有。今儿个,咱们就来走一波spring boot 整合 swagger 生成在线文档。(呼~~爽,感觉用了这个,就可以不用被前端大佬“骚扰”了)。介绍两种集成swagger的方式,越用越爽。写文档的时候可以用来和基友尬聊了(编程五分钟,扯淡两小时,一天就这么没了...) ##第一招 Without Starter 新建项目,pom 文件加上两个swagger必要的依赖。

    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

Swagger的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
     *
     * @return
     * @Api:修饰整个类,描述Controller的作用
     * @ApiOperation:描述一个类的一个方法,或者说一个接口
     * @ApiParam:单个参数描述
     * @ApiModel:用对象来接收参数
     * @ApiProperty:用对象接收参数时,描述对象的一个字段
     * @ApiResponse:HTTP响应其中1个描述
     * @ApiResponses:HTTP响应整体描述
     * @ApiIgnore:使用该注解忽略这个API
     * @ApiError:发生错误返回的信息
     * @ApiImplicitParam:一个请求参数
     * @ApiImplicitParams:多个请求参数
     */
    @Bean
    public Docket createRestApi() {

        /**添加head参数start*/
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("authorization").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        //添加head参数end
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("com.developlee.HangZhou.ZheJiang")
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //有该注解的生成doc
                .apis(RequestHandlerSelectors.basePackage("com.developlee.swagger"))   // 自行修改为自己的包路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars) //set Header
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("DevelopLee的Swagger在线文档")
                .description("嗯哼嗯哼额~~~swagger文档很强!")
                .termsOfServiceUrl("http://github.com/developlee")
                .version("1.0")
                .build();
    }
}

写个Controller类测试

@RestController
public class UserController {

    @GetMapping("/userInfo")
    @ApiOperation(notes = "获取用户信息", value = "get user info")
    public String getUserInfo(){
        return "getUserInfo";
    }

    @PostMapping("/addUser")
    @ApiOperation(notes = "添加用户信息", value = "add user info")
    @ApiImplicitParam(value = "添加用户", name = "add user", dataType = "java.lang.String", required = true)
    public String addUser(String str){
        return "addUser";
    }
}

启动项目...访问 localhost:8080/swagger-ui.html(我滴个龟龟,这就好了?)感动到哭,前端大佬们, see you la la~~(事实上我去找他们聊天了,感受下这个文档带给后端开发人员的福利,尤其是惰性开发人员,比如在座的所有人) image

第二招 With swagger-spring-boot-starter

这里介绍一个相当牛逼的工具,来自spring4all.com社区开源的swagger-spring-boot-starter。接下来我们就用这个依赖包开发swagger 文档。 pom.xml依赖

  <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.1.RELEASE</version>
  </dependency>

@EnableSwagger2Doc开启文档

@SpringBootApplication
@EnableSwagger2Doc
public class SwaggerStarterApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerStarterApplication.class, args);
    }
}

###配置示例:

swagger.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.7.1.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=developlee
swagger.contact.url=http://github.com/developlee
swagger.contact.email=developlee@163.com
swagger.base-package=com.developlee
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

swagger.globalOperationParameters[0].name=name one
swagger.globalOperationParameters[0].description=some description one
swagger.globalOperationParameters[0].modelRef=string
swagger.globalOperationParameters[0].parameterType=header
swagger.globalOperationParameters[0].required=true
swagger.globalOperationParameters[1].name=name two
swagger.globalOperationParameters[1].description=some description two
swagger.globalOperationParameters[1].modelRef=string
swagger.globalOperationParameters[1].parameterType=body
swagger.globalOperationParameters[1].required=false

// 取消使用默认预定义的响应消息,并使用自定义响应消息
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

###配置说明--默认配置

- swagger.enabled=是否启用swagger,默认:true
- swagger.title=标题
- swagger.description=描述
- swagger.version=版本
- swagger.license=许可证
- swagger.licenseUrl=许可证URL
- swagger.termsOfServiceUrl=服务条款URL
- swagger.contact.name=维护人
- swagger.contact.url=维护人URL
- swagger.contact.email=维护人email
- swagger.base-package=swagger扫描的基础包,默认:全扫描
- swagger.base-path=需要处理的基础URL规则,默认:/**
- swagger.exclude-path=需要排除的URL规则,默认:空
- swagger.host=文档的host信息,默认:空
- swagger.globalOperationParameters[0].name=参数名
- swagger.globalOperationParameters[0].description=描述信息
- swagger.globalOperationParameters[0].modelRef=指定参数类型
- swagger.globalOperationParameters[0].parameterType=指定参数存放位置,可选header,query,path,body.form
- swagger.globalOperationParameters[0].required=指定参数是否必传,true,false

###Path设置

management.context-path=/ops

swagger.base-path=/**
swagger.exclude-path=/ops/**, /error

上面的设置将解析所有除了/ops/开始以及spring boot自带/error请求路径。

其中,exclude-path可以配合management.context-path=/ops设置的spring boot actuator的context-path来排除所有监控端点。 ###分组配置

- swagger.docket.<name>.title=标题
- swagger.docket.<name>.description=描述
- swagger.docket.<name>.version=版本
- swagger.docket.<name>.license=许可证
- swagger.docket.<name>.licenseUrl=许可证URL
- swagger.docket.<name>.termsOfServiceUrl=服务条款URL
- swagger.docket.<name>.contact.name=维护人
- swagger.docket.<name>.contact.url=维护人URL
- swagger.docket.<name>.contact.email=维护人email
- swagger.docket.<name>.base-package=swagger扫描的基础包,默认:全扫描
- swagger.docket.<name>.base-path=需要处理的基础URL规则,默认:/**
- swagger.docket.<name>.exclude-path=需要排除的URL规则,默认:空
- swagger.docket.<name>.name=参数名
- swagger.docket.<name>.modelRef=指定参数类型
- swagger.docket.<name>.parameterType=指定参数存放位置,可选header,query,path,body.form
- swagger.docket.<name>.required=true=指定参数是否必传,true,false
- swagger.docket.<name>.globalOperationParameters[0].name=参数名
- swagger.docket.<name>.globalOperationParameters[0].description=描述信息
- swagger.docket.<name>.globalOperationParameters[0].modelRef=指定参数存放位置,可选header,query,path,body.form
- swagger.docket.<name>.globalOperationParameters[0].parameterType=指定参数是否必传,true,false

更多移步至 github.com

最后,以上示例代码可在我的github.com-swagger-starter以及github.com-swagger及中找到。 我的个人公众号:developlee的潇洒人生。 关注了也不一定更新,更新就不得了了。 qrcode_for_gh_2bd3f44efa21_258

© 著作权归作者所有

liululee
粉丝 127
博文 66
码字总数 90743
作品 0
杭州
程序员
私信 提问
加载中

评论(5)

天青色有雨
天青色有雨

引用来自“developlee的潇洒人生”的评论

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?

引用来自“developlee的潇洒人生”的评论

Spring Boot 2.0.4.RELEASE Swagger 2.7.0

引用来自“天青色有雨”的评论

项目中用的spring boot版本还是1.5.x的,请问spring boot1.5.x能否整合swagger 2.9.2?据了解2.9版本视图化界面更完善些,2.7版本还是有点差距的
版本差距不大,另外事实上,我觉得您应该自己动手去尝试,这样远比我告诉您强得多

各个版本我都已经尝试整合了,真实的效果还是得靠开发规范的约束,不过在测试阶段是可以用的
liululee
liululee 博主

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?

引用来自“developlee的潇洒人生”的评论

Spring Boot 2.0.4.RELEASE Swagger 2.7.0

引用来自“天青色有雨”的评论

项目中用的spring boot版本还是1.5.x的,请问spring boot1.5.x能否整合swagger 2.9.2?据了解2.9版本视图化界面更完善些,2.7版本还是有点差距的
版本差距不大,另外事实上,我觉得您应该自己动手去尝试,这样远比我告诉您强得多
天青色有雨
天青色有雨

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?

引用来自“developlee的潇洒人生”的评论

Spring Boot 2.0.4.RELEASE Swagger 2.7.0
项目中用的spring boot版本还是1.5.x的,请问spring boot1.5.x能否整合swagger 2.9.2?据了解2.9版本视图化界面更完善些,2.7版本还是有点差距的
liululee
liululee 博主

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?
Spring Boot 2.0.4.RELEASE Swagger 2.7.0
天青色有雨
天青色有雨
请问整合的是2.9版本的么?spring boot的版本是多少?
Spring Boot学习笔记

多模块开发 [SpringBoot学习]-IDEA创建Gradle多Module结构的SpringBoot项目 RabbitMQ RabbitMQ 安装 linux安装RabbitMQ详细教程 Ubuntu 16.04 RabbitMq 安装与运行(安装篇) ubantu安装...

OSC_fly
2018/07/26
0
0
程序猿DD/swagger-butler

Swagger Butler Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,...

程序猿DD
2018/05/25
0
0
Spring Boot 学习资料收集

导读: 从第一次接触Spring Boot 至今已经有半年多了,在这期间也浏览了许多和Spring Boot 相关的书籍及文章,公司里面的许多项目也一直在使用Spring Boot。 关于Spring Boot的一些看法: Sp...

yangrd
2017/03/02
0
0
使用Swagger2构建Spring Boot RESTful AIP 文档

上一篇我们介绍了如何使用Spring Boot快速构建RESTful API “Spring Boot与RESTful API ” ,本篇则介绍一个配合Spring Boot快速构建RESTful文档的工具 由于Spring Boot具有快速开发、便捷部...

老虎是个蛋蛋
2016/12/23
1K
5
精通Spring Boot——第三篇:详解WebMvcConfigurer接口

SpringBoot 确实为我们做了很多事情, 但有时候我们想要自己定义一些Handler,Interceptor,ViewResolver,MessageConverter,该怎么做呢。在Spring Boot 1.5版本都是靠重写WebMvcConfigure...

developlee的潇洒人生
2018/10/03
2K
0

没有更多内容

加载失败,请刷新页面

加载更多

最简单的获取相机拍照的图片

  import android.content.Intent;import android.graphics.Bitmap;import android.os.Bundle;import android.os.Environment;import android.provider.MediaStore;import andr......

MrLins
34分钟前
4
0
说好不哭!数据可视化深度干货,前端开发下一个涨薪点在这里~

随着互联网在各行各业的影响不断深入,数据规模越来越大,各企业也越来越重视数据的价值。作为一家专业的数据智能公司,个推从消息推送服务起家,经过多年的持续耕耘,积累沉淀了海量数据,在...

个推
36分钟前
7
0
第三方支付-返回与回调注意事项

不管是支付宝,微信,还是其它第三方支付,第四方支付,支付机构服务商只要涉及到钱的交易都要进行如下校验,全部成功了才视为成功订单 1.http请求是否成功 2.校验商户号 3.校验订单号及状态...

Shingfi
39分钟前
4
0
简述Java内存分配和回收策略以及Minor GC 和 Major GC(Full GC)

内存分配: 1. 栈区:栈可分为Java虚拟机和本地方法栈 2. 堆区:堆被所有线程共享,在虚拟机启动时创建,是唯一的目的是存放对象实例,是gc的主要区域。通常可分为两个区块年轻代和年老代。更...

DustinChan
44分钟前
6
0
Excel插入批注:可在批注插入文字、形状、图片

1.批注一直显示:审阅选项卡-------->勾选显示批注选项: 2.插入批注快捷键:Shift+F2 组合键 3.在批注中插入图片:鼠标右键点击批注框的小圆点【重点不可以在批注文本框内点击】----->调出批...

东方墨天
今天
6
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部