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. Relativelayout和LinearLayout对比分析

    分析之前先了解下View的绘制流程 首先view在windows中的布局样式如下图: view绘制在windows,windows与DecoverView的交互在VIewRoot中进行. view绘制 ...

  2. [POJ1273][USACO4.2]Drainage Ditches (网络流最大流)

    题意 网络流最大流模板 思路 EK也不会超时 所以说是一个数据比较水的模板题 但是POJ有点坑,多组数据,而且题目没给 哭得我AC率直掉 代码 用的朴素Dinic #include<cstdio ...

  3. go语言数据库操作,xorm框架

    待续............................................... 连接数据库 db, err := xorm.NewEngine("mysql", ...

  4. js实现八皇后,回溯法

    八皇后问题:将八个皇后摆在一张8*8的国际象棋棋盘上,使每个皇后都无法吃掉别的皇后,一共有多少种摆法? 两个皇后不能同时在同一行,同一列,和斜对角线的位置上,使用回溯法解决. 从第一行选个位置开始放棋 ...

  5. myeclipse中配置自己安装的Tomcat

    myeclipse中配置自己安装的Tomcat 在myeclipse中配置好jdk,Tomcat之后,如果是web项目需要部署运行,但在部署时发现配置好的Tomcat没有显示,只显示了myeclips ...

  6. 等高布局display:table

    display:table用法: 父元素:display:table; 子元素:display:table-cell; 注:使用display:table-cell元素部分出现空白缝隙的问题:设置 . ...

  7. linux 做了raid后,硬盘坏了更换问题

    系统做完raid1后发现 raid盘坏了,硬盘都是热插拔的,更换后,需要简单配置一下才能自动进行镜像拷贝. 在pd mgmt 页面,选择新加入的硬盘,按F2,选择 make global HS选项 选 ...

  8. 使用IDEA时跳转到.class的解决办法

    项目背景:jdk1.8 软件环境:IDEA 问题: 1. 两个不同的项目,在A项目中写了一个实体类.B项目中引用.在B项目中CTRL+鼠标左键点击进入,正常情况下是进入了源码文件,也就是.JAVA文件 ...

  9. 在浏览器输入URL时发生了什么

    浏览器器检查cache,如果请求对象已经缓存并且是最新的,执行第9步. 浏览器询问操作系统,请求服务器的IP地址 操作系统进行DNS查找,然后告诉浏览器服务器的IP 浏览器和服务器简历一个TCP连接( ...

  10. java中class文件与jar文件

    1. JAR 文件包 JAR 文件就是 Java Archive File,顾名思意,它的应用是与 Java 息息相关的,是 Java 的一种文档格式.JAR 文件非常类似 ZIP 文件——准确的说, ...