由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。
这样一来,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
<!-- more -->
由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API
使用
加入依赖
<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>
创建Swagger2配置类 (第一种)
package com.tjjp.common.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Swaager API文档配置 */ public class SwaggerConfig extends WebMvcConfigurerAdapter { public Docket docket() { return new Docket(DocumentationType.SWAGGER_2).groupName("swagger接口文档") .apiInfo(new ApiInfoBuilder().title("swagger接口文档") .contact(new Contact("Stone", "", "[email protected]")).version("1.0").build()) .select().paths(PathSelectors.any()).build(); } //解决静态资源无法访问的问题 public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars*") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
创建Swagger2配置类 (第二种)
public class Swagger2 { public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("cn.saytime.web")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger构建api文档") .description("简单优雅的restfun风格,http://www.1314sl.com") .termsOfServiceUrl("http://www.1314sl.com") .version("1.0") .build(); } }
启动Swagger2
//在程序入口的地方加上注解 @EnableSwagger2 value = "com.tjjp.dao") ( public class TjjplmApplication { public static void main(String[] args) { SpringApplication.run(TjjplmApplication.class, args); } }
Restful 接口编写和文档编写
package com.tjjp.contorller; import com.tjjp.dao.TNoticeMapper; import com.tjjp.model.TNotice; import com.tjjp.service.TNoticeService; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; public class NoticeContorl { TNoticeService TNservier; value="获取NEW公告信息", notes="最新的一条公告") ( value="GetNoticeNewTopOne") ( public TNotice GetNoticeNewTopOne(){ //TNservier.select TNotice tn=new TNotice(); return tn; } value="获取公告(List)分页数据", notes="分页查询公告信息") ( ({ name = "page", value = "当前页数", required = true, dataType = "Integer"), ( name = "site", value = "每页多少条数据", required = true, dataType = "Integer") ( }) value="GetPageList") ( public List<TNotice> selectPageList( ("page") Integer page, "site") Integer site,TNotice tn){ ( List<TNotice> tNotices = TNservier.selectPageList(tn, page, site); return tNotices; } //使用该注解忽略这个API value="/GetAllNotice",method = RequestMethod.POST) ( public List<TNotice> GetAllNotice(){ return TNservier.selectByExample(null); } name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path") ( "/GetNotice/{id}") ( public TNotice GetNotice( int id){ return TNservier.selectByPrimaryKey(id); } }
swagger-ui.html 进入
© 著作权归作者所有
转载请保留原链接地址