Swagger2 方式,一定会让你有不一样的开发体验:功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

v添加pom依赖

        <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>

v配置swagger-ui

spring-boot有自己的一套web端拦截机制,若需要看到swagger发布的api文档界面,需要做一些特殊的配置,将springfox-swagger-ui包中的ui界面暴露给spring-boot资源环境。

package com.demo.filter;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import javax.annotation.Resource; /**
* Created by toutou on 2018/12/30.
*/
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Resource
private MyTestInterceptor myTestInterceptor; @Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

v配置API文档

spring-boot 和 swagger 整合时,可以通过注解注入相关配置。通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹,另外可以指定API文档页的标题和描述信息等内容。

package com.demo.common;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2; /**
* Created by toutou on 2018/12/30.
*/
@Configuration
@EnableSwagger2
public class Swagger2 { @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试项目 RESTful APIs")
.description("测试项目后台api接口文档")
.version("1.0.0")
.build();
} }

注意把com.demo.controller更换成Controller的包名

vAPI文档编写示例

我们一般在Controller层,将详尽的API接口输入输出在代码中通过注解进行相关描述,下面给出一个接口描写示例,具体的写法可以参考其api文档的实例:

package com.demo.controller;

import com.demo.pojo.UserDetails;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody; import javax.servlet.http.HttpServletRequest; /**
* Created by toutou on 2018/12/30.
*/
@Api(value = "PageController", description = "用户登录登出接口")
@Controller
@RequestMapping("/")
public class PageController { @ApiOperation(value="用户登录", notes="用户登录接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),
@ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")
})
@RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})
@ResponseBody
public ModelMap login(UserDetails data, HttpServletRequest request){
// todo 实现
return null;
} }

v效果

完成API文档的编写工作之后,正常启动spring-boot,假如后台端口为8080,那么访问http://localhost:8081/swagger-ui.html,可以访问到如下界面:

通过该界面,不仅可以看到自动生成的所有API文档信息,还可以对任意接口进行在线测试,非常方便,仿佛可以卸载Postman似的。〔^.べ〕:

v源码地址

https://github.com/toutouge/javademosecond/tree/master/hellospringboot

作  者:请叫我头头哥

出  处:http://www.cnblogs.com/toutou/

关于作者:专注于基础平台的项目开发。如有问题或建议,请多多赐教!

版权声明:本文版权归作者和博客园共有,欢迎转载,但未经作者同意必须保留此段声明,且在文章页面明显位置给出原文链接。

特此声明:所有评论和私信都会在第一时间回复。也欢迎园子的大大们指正错误,共同进步。或者直接私信

声援博主:如果您觉得文章对您有帮助,可以点击文章右下角推荐一下。您的鼓励是作者坚持原创和持续写作的最大动力!

SpringBoot入门教程(二十)Swagger2-自动生成RESTful规范API文档的更多相关文章

  1. 利用Swagger2自动生成对外接口的文档

    一直以来做对外的接口文档都比较原始,基本上都是手写的文档传来传去,最近发现了一个新玩具,可以在接口上省去不少麻烦. swagger是一款方便展示的API文档框架.它可以将接口的类型最全面的展示给对方开 ...

  2. apidoc 生成Restful web Api文档

    在服务器项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office写一个文档,不够直观.下面介绍一种工具生成Apidoc.,该工具是Nodejs的模块,请务必在使用前安装好nodejs ...

  3. 使用apidoc 生成Restful web Api文档

    在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观.好在git上的开源大神提供了生成文档的工具,so来介绍一下! 该工具是Nodejs的 ...

  4. 使用apidoc 生成Restful web Api文档——新手问题与解决方法

    使用apidoc工具来给项目做接口文档,不仅有合理的源码注释,还可以生成对应的文档.是给源码写备注的一个极佳实践. 工具名称:apiDoc Git地址:https://github.com/apido ...

  5. 无废话ExtJs 入门教程二十[数据交互:AJAX]

    无废话ExtJs 入门教程二十[数据交互:AJAX] extjs技术交流,欢迎加群(521711109) 1.代码如下: 1 <!DOCTYPE html PUBLIC "-//W3C ...

  6. SpringBoot进阶教程(二十九)整合Redis 发布订阅

    SUBSCRIBE, UNSUBSCRIBE 和 PUBLISH 实现了 发布/订阅消息范例,发送者 (publishers) 不用编程就可以向特定的接受者发送消息 (subscribers). Ra ...

  7. SpringBoot入门教程(二)CentOS部署SpringBoot项目从0到1

    在之前的博文<详解intellij idea搭建SpringBoot>介绍了idea搭建SpringBoot的详细过程, 并在<CentOS安装Tomcat>中介绍了Tomca ...

  8. 【工具篇】利用DBExportDoc V1.0 For MySQL自动生成数据库表结构文档

    对于DBA或开发来说,如何规范化你的数据库表结构文档是灰常之重要的一件事情.但是当你的库,你的表排山倒海滴多的时候,你就会很头疼了. 推荐一款工具DBExportDoc V1.0 For MySQL( ...

  9. 自动生成并导出word文档

    今天很荣幸又破解一现实难题:自动生成并导出word文档 先看页面效果: word效果: 代码: 先搭建struts2项目 创建action,并在struts.xml完成注册 <?xml vers ...

随机推荐

  1. 极简科普 1:什么是 VOIP

    VoIP 的全称是 Voice over Internet Protocol.简单说,就是用过 IP 网络进行即时的语音/视频通信.注意,这里只强调了在传输过程中有使用 IP 网络,并没有说只通过 I ...

  2. 展开被 SpringBoot 玩的日子 《 五 》 spring data jpa 的使用

    在上篇文章< 展开被 SpringBoot 玩的日子 < 二 >WEB >中简单介绍了一下spring data jpa的基础性使用,这篇文章将更加全面的介绍spring da ...

  3. 展开被 SpringBoot 玩的日子 《 四 》 Session 会话共享

    共享Session-spring-session-data-redis 分布式系统中,sessiong共享有很多的解决方案,其中托管到缓存中应该是最常用的方案之一. Spring Session官方说 ...

  4. DWM1000 定位操作流程--[蓝点无限]

    蓝点DWM1000 模块已经打样测试完毕,有兴趣的可以申请购买了,更多信息参见 蓝点论坛 1烧录HEX文件 使用ST-LINK utility 烧录HEX文件,分别烧录三个基站以及一个标签,烧录基站时 ...

  5. vbs脚本实现qq定时发消息(初级)

    vbs脚本实现QQ消息定时发送 目标 批处理又称为批处理脚本,强大的强大功能可以高效得实现很多功能,例如批量更改文件格式,批量进行文件读写,今天我们的目标是用vbs脚本编写可以发送qq消息的脚本,并利 ...

  6. 马昕璐 201771010118《面向对象程序设计(java)》第十五周学习总结

    第一部分:理论知识学习部分 JAR文件:将.class文件压缩打包为.jar文件后,使用ZIP压缩格式,GUI界面程序就可以直接双击图标运行. 既可以包含类文件,也可以包含诸如图像和声音这些其它类型的 ...

  7. [LeetCode] Length of Longest Fibonacci Subsequence 最长的斐波那契序列长度

    A sequence X_1, X_2, ..., X_n is fibonacci-like if: n >= 3 X_i + X_{i+1} = X_{i+2} for all i + 2 ...

  8. [LeetCode] Find And Replace in String 在字符串中查找和替换

    To some string S, we will perform some replacement operations that replace groups of letters with ne ...

  9. R语言读入数据库的中英名词互译测试并计分脚本(考试用)

    1. 分子生物学中英文.csv,输入文件,两列,以tab键分隔的txt文本,没有列名 2. 错误的名解.csv, 如果在测试中拼写错误,会写出到这个文件,可用这个容易犯错的名词进行新的测试 3. 注意 ...

  10. Widows 和Linux 查看和操作端口方法

    Windows 打开cmd1.netstat -n查看本机的使用的所有端口①.proto表示协议 有tcp和udp两种②.Local Address 表示本机的IP,后面跟的是我们使用的端口号③.Fo ...