文档章节

SpringBoot入门——使用Swagger构建Restful API文档

DLQ丁
 DLQ丁
发布于 2017/07/28 18:48
字数 1327
阅读 144
收藏 2

行业解决方案、产品招募中!想赚钱就来传!>>>

SpringBoot入门——使用Swagger2构建Restful API文档

自己写程序测试时写的,不喜勿喷,可能有错,欢迎纠正

一、背景

        由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

        这样一来,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

  • 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
  • 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

        为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

二、Swagger简介

        Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。

        Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

 

三、SpringBoot中应用Swagger2

(1)、新建Maven项目

项目名称:springboot

(2)、在pom中引入Springboot项目需要的包

新建Maven项目,往其中pom.xml中引入Springboot需要的包

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.springboot</groupId>
	<artifactId>spring-boot2</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>springboot</name>
	<url>http://maven.apache.org</url>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.5.4.RELEASE</version>
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<!-- web -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- Springboot devtools热部署 依赖包 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<optional>true</optional>
			<scope>true</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin </artifactId>
				<configuration>
				<!-- 如果没有该项配置,devtools不会起作用,即应用不会restart -->
					<fork>true</fork>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

(3)、在pom中引入Swagger需要的包

       	<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>

(4)、创建Swagger2配置类

包名:com.springboot.config

类名:SwaggerConfig

package com.springboot.config;

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;

@Configuration
// 启用swagger
@EnableSwagger2
public class SwaggerConfig {
	  @Bean
	    public Docket createRestApi() {
	        return new Docket(DocumentationType.SWAGGER_2)
	                .apiInfo(this.apiInfo())
                    .groupName("XX组")
	                .useDefaultResponseMessages(false)
	                .enableUrlTemplating(false)
	                .select()
	                .apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
	                .paths(PathSelectors.any())
	                .build();
	    }

	    private ApiInfo apiInfo() {
	        return new ApiInfoBuilder()
	                .title("Spring Boot Swagger2 By Test")
	                .description("XX项目API")
	                .termsOfServiceUrl("127.0.0.1:8080/test/")
	                .version("0.0.1")
	                .build();
	    }
}

参数说明:

----------------------------------------------------------------------------------

  • @Configuration:声明此类为配置类,让Spring加载
  • @EnableSwagger2:启用Swagger2

----------------------------------------------------------------------------------

  • apiInfo():创建该Api的基本信息
  • groupName():设置组名
  • useDefaultResponseMessages():使用默认的响应信息,一般设置false
  • enableUrlTemplating(false):使模板的URL

----------------------------------------------------------------------------------

  • apis():扫描哪些包
  • PathSelectors.any():任何满足条件的路径

----------------------------------------------------------------------------------

(5)、创建Controller类

包名:com.springboot.controller;

类名:HelloController

package com.springboot.controller;

import static org.springframework.util.MimeTypeUtils.APPLICATION_JSON_VALUE;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.springboot.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/test")
@Api(tags="与检查单有关的接口")
public class HelloController {

	@ApiOperation(value = "获得hello字符串JSON", response = String.class, produces = APPLICATION_JSON_VALUE
			,notes = "根据User对象创建用户")
	@RequestMapping(value = { "/hello" }, method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}

	@ApiOperation(value = "修改用户", response = String.class, produces = APPLICATION_JSON_VALUE
			,notes = "根据id修改用户")
	@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
	@RequestMapping(value = { "/modifyUser" }, method = RequestMethod.POST) 
	public User modifyUser(@RequestBody User user) {
		user.setName("张三");
		user.setAge(20);
		return user;
	}

}

参数说明:

----------------------------------------------------------------------------------

  • @Api:对Controller项的标题描述信息设置
  • @ApiOperation:对接口信息进行描述
  1. name:参数名
  2. value:参数描述信息
  3. required:是否可以发送请求信息进行测试
  4. dataType:数据类型
  • @ApiImplicitParam:对接口的方法的参数进行描述
  1. value:操作项名字设置
  2. response:返回类型设置
  3. response:返回数据格式
  4. notes:此项的描述信息

----------------------------------------------------------------------------------

三、管理接口的地址

http://localhost:8080/swagger-ui.html

 

 

DLQ丁
粉丝 31
博文 18
码字总数 27886
作品 0
丰台
程序员
私信 提问
加载中
请先登录后再评论。
CDH5: 使用parcels配置lzo

一、Parcel 部署步骤 1 下载: 首先需要下载 Parcel。下载完成后,Parcel 将驻留在 Cloudera Manager 主机的本地目录中。 2 分配: Parcel 下载后,将分配到群集中的所有主机上并解压缩。 3 激...

cloud-coder
2014/07/01
6.8K
1
beego API开发以及自动化文档

beego API开发以及自动化文档 beego1.3版本已经在上个星期发布了,但是还是有很多人不了解如何来进行开发,也是在一步一步的测试中开发,期间QQ群里面很多人都问我如何开发,我的业余时间实在...

astaxie
2014/06/25
2.7W
21
树莓派(Raspberry Pi):完美的家用服务器

自从树莓派发布后,所有在互联网上的网站为此激动人心的设备提供了很多有趣和具有挑战性的使用方法。虽然这些想法都很棒,但树莓派( RPi )最明显却又是最不吸引人的用处是:创建你的完美家用...

异次元
2013/11/09
5.1K
8
5分钟 maven3 快速入门指南

前提条件 你首先需要了解如何在电脑上安装软件。如果你不知道如何做到这一点,请询问你办公室,学校里的人,或花钱找人来解释这个给你。 不建议给Maven的服务邮箱来发邮件寻求支持。 安装Mav...

fanl1982
2014/01/23
1.2W
6
代码生成器--Codgen

Codgen是一个基于数据库元数据模型,使用freemarker模板引擎来构建输出的代码生成器。freemarker的数据模型结构通常来说都是一个Map树状结构模型,codgen也不例外,它的数据模型这棵树的根节...

黄天政
2013/01/29
1.4W
2

没有更多内容

加载失败,请刷新页面

加载更多

Linux拜拜!微软给WSL加入GPU支持,Windows终于迎来命令行包管理工具

点击蓝字“ 大白技术控 ”关注我哟 加个“星标★”,每日良时,好文必达! 白交 发自 凹非寺 量子位 报道 | 公众号 QbitAI 看完昨晚微软Build大会,虽然开发者不能亲自到现场,但看到WSL更新...

大白技术控
05/25
0
0
GraphQL

网文、分享汇总 干货分享 | GraphQL 数据聚合层 http://www.sohu.com/a/235978606_205771 awesome-graphql https://github.com/chentsulin/awesome-graphql 一些graphql相关的java项目 周边项......

素雷
12分钟前
4
0
如何在jQuery中选择具有多个类的元素? - How can I select an element with multiple classes in jQuery?

问题: I want to select all the elements that have the two classes a and b . 我想选择具有两个类a和b所有元素。 <element class="a b"> So, only the elements that have both classe......

javail
35分钟前
5
0
MySql查询所有字段不为空值的数据及Mybatis的#号和$符的区别引起的问题

1.MySql查询所有字段不为空值的数据 搜了一上午搜不到,最后用Mybatis的foreach标签,先查询出表字段, SELECT COLUMN_NAMEFROM INFORMATION_SCHEMA.ColumnsWHERE table_name='lltest'...

不忘初心牢记使命
35分钟前
32
0
五分钟搞定WebRTC视频录制

WebRTC中文社区是一个为大家解决在使用WebRTC当中遇到问题所建立的社区,欢迎更多学习和使用WebRTC的人加入进来,一起建设。 视频录制 在之前的文章里我们提到过视频录制的两种方式:客户端录...

死磕音视频
42分钟前
13
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部