Spring集成Swagger2,提供RestFul API

Posted 2023-03-01 zhenghuasheng

本文将介绍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/","[e-mail]"))
                .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的序列化支持。