筱进GG的gravatar头像
筱进GG2017-11-08 19:54:46
Spring Boot学习(五)之使用Swagger2构建强大的RESTful API文档

       随着前后端的分离,接口文档变的尤其重要,今天我们来说一说用SWAGGER2,来风骚的生成api文档。配置很简单,废话少说,直接上代码:

pom.xml文件

<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.5.8.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

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

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

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

	</dependencies>
	
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

首先,我们需要一个Spring Boot实现的RESTful API工程,若您没有做过这类内容,建议先阅读
Spring Boot构建一个较为复杂的RESTful APIs和单元测试

创建Swagger2配置类

在Application.java启动类的同级创建Swagger2的配置类Swagger2。

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaojingg.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注:http://www.zuidaima.com/user/2068438360459264/blog.htm")
                .termsOfServiceUrl("http://www.zuidaima.com/user/2068438360459264/blog.htm")
                .contact("筱进GG")
                .version("1.0")
                .build();
    }

}

如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。

添加文档内容

在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

添加上之前Spring Boot学习(三)之构建RESTful API与单元测试 后;

启动启动类;

访问:http://localhost:8080/swagger-ui.html
Spring Boot学习(五)之使用Swagger2构建强大的RESTful API文档

就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求,以POST类型的/users请求为例,可找到上述代码中我们配置的Notes信息以及参数user的描述信息,如下图所示。

Spring Boot学习(五)之使用Swagger2构建强大的RESTful API文档配置完成了, 小伙伴们试试吧!


打赏

已有1人打赏

最代码官方的gravatar头像

分享到:

最近浏览
wjkbl7532017年12月22日
暂无贡献等级
传奇码农2017年12月14日
最代码贡献等级说明
yuliu33442017年11月21日
暂无贡献等级
tuziilm2017年11月20日
最代码贡献等级说明
kisn8882017年11月20日
最代码贡献等级说明
Scorpion_java2017年11月20日
暂无贡献等级
wkc2017年11月20日
暂无贡献等级
俏飘佳人2017年11月20日
最代码贡献等级说明
feia12362017年11月20日
最代码贡献等级说明
wll20162017年11月17日
最代码贡献等级说明
mlfxxy2017年11月16日
暂无贡献等级
修罗2017年11月16日
暂无贡献等级
china_02212017年11月16日
暂无贡献等级
羊驼子2017年11月15日
暂无贡献等级
newlife19912017年11月15日
暂无贡献等级
ha78gs2017年11月15日
暂无贡献等级
186755463662017年11月15日
暂无贡献等级
renjunyou2017年11月15日
暂无贡献等级
大懒虫2017年11月15日
最代码贡献等级说明
weienqing2017年11月15日
最代码贡献等级说明
顶部客服微信二维码底部
>扫描二维码关注最代码为好友扫描二维码关注最代码为好友