筱进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头像

分享到:

最近浏览
wll2016昨天
暂无贡献等级
mlfxxy前天
暂无贡献等级
修罗前天
暂无贡献等级
暂无贡献等级
羊驼子11月15日
暂无贡献等级
newlife199111月15日
暂无贡献等级
ha78gs11月15日
暂无贡献等级
1867554636611月15日
暂无贡献等级
renjunyou11月15日
暂无贡献等级
大懒虫11月15日
最代码贡献等级说明
weienqing11月15日
最代码贡献等级说明
coding喵11月14日
最代码贡献等级说明
喜你人多11月14日
暂无贡献等级
是时候了11月14日
暂无贡献等级
idtompen11月13日
暂无贡献等级
liu00111月13日
最代码贡献等级说明
ReakerL11月13日
最代码贡献等级说明
cugaifmsg11月13日
暂无贡献等级
lcjz9911月13日
最代码贡献等级说明
水心木支11月11日
最代码贡献等级说明
顶部客服微信二维码底部
>扫描二维码关注最代码为好友扫描二维码关注最代码为好友