Swagger2

https://www.cnblogs.com/jtlgb/p/8532433.html

1 手写Api文档的几个痛点：

• 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时
• 接口返回结果不明确
• 不能直接在线测试接口，通常需要使用工具，比如postman
• 接口文档太多，不好管理

Swagger也就是为了解决这些问题，直接生成接口文档的方式。当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

2 swagger2的使用

2.1 依赖

compile "io.springfox:springfox-swagger2:2.7.0"
    compile 'io.springfox:springfox-swagger-ui:2.7.0'

2.2 配置类

@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

注解 @EnableSwagger2 表示开启Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select().apis(RequestHandlerSelectors.basePackage("com.system.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
                //页面标题
                .title("内蒙古医院探视信息管理项目")
                //版本号
                .version("1.0.2")
                //描述
                .build();

    }
}

用**@Configuration注解该类，等价于XML中配置beans**；用**@Bean标注方法等价于XML中配置bean**。

2.3 注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

2.4 实例

@RestController
@Api(tags = "sysArea",description = "病区相关操作")
@RequestMapping(value = "/sysArea")
@CheckException(reason = "检查病区操作参数的合法性")
public class SysAreaController {

    @Resource
    private SysAreaService sysAreaService;

    @ApiOperation(value = "根据id查询病区")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseStatus(HttpStatus.OK)
    public SysArea get(@PathVariable int id){
        return sysAreaService.get(id);
    }
 ｝

3 用到的注解

Spring MVC中最为常用的几个核心注解：

• @Controller：修饰class，用来创建处理http请求的对象

• @RestController：Spring4之后加入的注解，原来在@Controller中返回json需要@ResponseBody来配合，如果直接用@RestController替代@Controller就不需要再配置@ResponseBody，默认返回json格式。

• @RequestMapping：配置url映射

参数绑定的注解：

• @PathVariable
• @ModelAttribute
• @RequestParam
• @RequestBody