Spring集成Swagger2,提供RestFul API

Posted zhenghuasheng

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Spring集成Swagger2,提供RestFul API相关的知识,希望对你有一定的参考价值。

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

效果图:

第一步:maven依赖加入

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

第二步:Swagger2配置类添加

/**
 * http://localhost:8090/swagger-ui.html
 * @author zhenghuasheng
 * @date 2017/11/8.11:07
 */
@Configuration
@EnableWebMvc
@EnableSwagger2
public class Swagger2Config 

    @Bean
    public Docket createRestApi() 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    
    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
                .title("客服系统RESTful APIs")
                .description("HTTP方法、参数说明,以及模拟实时调用结果展示,使用方法请自行参照Swagger2文档")
                .termsOfServiceUrl("http://192.168.4.105:20400/")
                .contact(new  Contact("zhs","http://192.168.4.105:20400/","zhenghuasheng@aicai.group.com"))
                .version("1.0.0")
                .build();
    

第三步:spring配置文件添加Swagger2静态文件配置

    <mvc:default-servlet-handler/>
    <!--静态文件标示  -->
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

第四步:拦截器检查
如果项目中有拦截器配置,需要将Swagger2的静态文件访问放行

    <mvc:exclude-mapping path="/swagger*/**"/>
    <mvc:exclude-mapping path="/v2/**"/>
    <mvc:exclude-mapping path="/webjars/**"/>

第五步:添加API描述

/**
 * Created by zhenghuasheng on 2017/9/11.16:34
 */
@Api(value = "AchieveController" ,description = "订单业绩查询和导出")
@Controller
@RequestMapping("/achieve")
public class AchieveController 
    @Autowired
    private ActivityUserFacade activityUserFacade;

    private static Logger logger = LoggerFactory.getLogger(AchieveController.class);

    /**
     * 
     * @param request
     * @param page
     * @param pageSize
     * @return
     */
    @ApiOperation(value = "主动服务订单业绩列表", notes = "getOrderKpis",httpMethod = "POST")
    @ResponseBody
    @RequestMapping(value = "/list")
    public ResultVo<JqGridPaperVo> getOrderKpis(HttpServletRequest request, @RequestParam(defaultValue = "1") Integer page, @RequestParam(defaultValue = "20") Integer pageSize) 

    

第六步:启动服务,访问http://ip:port/swagger-ui.html

Swagger2文档:http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

注解说明:
@Api:用在类上,说明该类的作用

@ApiOperation:用在方法上,说明方法的作用,标注在具体请求上,value和notes的作用差不多,都是对请求进行说明;tags则是对请求进行分类的,比如你有好几个controller,分别属于不同的功能模块,那这里我们就可以使用tags来区分了,看上去很有条理

@ApiImplicitParams:用在方法上包含一组参数说明

@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

paramType:参数放在哪个地方

header–>请求参数的获取:@RequestHeader

query–>请求参数的获取:@RequestParam

path(用于restful接口)–>请求参数的获取:@PathVariable

body(不常用)

form(不常用)

name:参数名

dataType:参数类型

required:参数是否必须传

value:参数的意思

defaultValue:参数的默认值

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

code:数字,例如400

message:信息,例如”请求参数没填好”

response:抛出异常的类

@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)表明这是一个被swagger框架管理的model,用于class上

@ApiModelProperty 这里顾名思义,描述一个model的属性,就是标注在被标注了@ApiModel的class的属性上,这里的value是对字段的描述,example是取值例子,注意这里的example很有用,对于前后端开发工程师理解文档起到了关键的作用,因为会在api文档页面上显示出这些取值来;这个注解还有一些字段取值,可以自己研究,举例说一个:position,表明字段在model中的顺序

新版本 swagger-bootstrap-ui :http://www.oschina.net/news/91637/swagger-bootstrap-ui-1-7

问题总结:

1,SpringMVC中使用FastJsonHttpMessageConverter时Swagger2失效的解决办法

FastJson是阿里巴巴开源的高性能JSON转换工具。我们在使用Spring MVC需要进行JSON转换时,通常会使用FastJson提供的FastJsonHttpMessageConverter。但是在我们使用了Swagger2的工程中使用它之后,我们的Api文档就无法工作了(虽然swagger-ui界面可以展现,但是没有任何api内容,并且通过访问/v2/api-docse,我们得到的返回时,而不是之前的文档配置内容了

更新fastjson版本
更新fastjson版本为1.2.10以上,在之前的版本中FastJsonHttpMessageConverter没有暴露fastjson对Serializer配置。可以方便我们加入对springfox.documentation.spring.web.json.Json的序列化支持。

以上是关于Spring集成Swagger2,提供RestFul API的主要内容,如果未能解决你的问题,请参考以下文章

Spring Boot之Swagger2集成

spring boot集成swagger2

Spring Boot 入门:集成 swagger2

spring cloud:Swagger2的集成

Spring boot - 集成Swagger2

spring boot 1.5.4 集成Swagger2构建Restful API(十八)