swagger的使用

1、为什么使用swagger

Swagger是一种用于构建、文档化和调试RESTful API的开源框架。

2、如何引入？

可以使用bootstrapui来使得页面操作更加简洁。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

3、配置类

@Configuration
@EnableSwagger2 
public class Swagger2Config {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //此处参数为ApiInfo对象
                //指定构建api文档的详细信息的方法
                .apiInfo(apiInfo())
                .select()
                //指定构建api接口的包路径-指定具体包路径
//                .apis(RequestHandlerSelectors.basePackage("com.provider.controller"))
                //指定构建api接口的包路径-此处为所有包（未指定）
                .apis(RequestHandlerSelectors.any())
                //访问路径下面的接口
//                .paths(PathSelectors.any())
//                .paths(PathSelectors.ant("/libai/**"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //可根据url路径设置那些请求加入文档，忽略哪些请求
                .paths(PathSelectors.any())
                .build()
                //分组管理可以与哪个访问路径结合使用
//                .groupName("用户管理")
                ;
    }


    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //界面标题
                .title("Swagger2构建Restful API文档")
                //接口描述
                .description("后端API接口文档展示")
                //联系方式，联系人-网址-邮箱
                .contact(new Contact("name","https://xxx.com/libai","xxx@163.com"))
                //版本信息
                .version("1.0.0")
                //证书描述
                .license("访问主页")
                //证书地址
                .licenseUrl("xxx.com")
                //系统服务网址
                .termsOfServiceUrl("xxx.com")
                .build();
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

4、常用注释

@Api(tags = “类业务名称”)
@ApiOperation(value = “接口名称”,notes = “接口描述”)
@ApiImplicitParams 注解是和 @ApiImplicitParam 注解配合使用的。
@ApiImplicitParams 注解描述的是一组请求参数，而单个请求参数是由@ApiImplicitParam注解来描述的。
name：参数名
value：参数解释
required：参数是否必须
dataType：参数类型
paramType：
- header：请求头
- query：?param=value的形式
- path：路径，Restful风格接口
- body：请求体
- form：以form表单的形式提交

@RestController
@RequestMapping("/parent")
@Slf4j
@RequiredArgsConstructor
@Api(tags = "类业务名称")
public class MyController {

    private final HisController hisController;

    @ApiOperation(value = "接口名称",notes = "接口描述")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "createTime", value = "创建时间：yyyy-MM-dd", required = true, dataType = "String", paramType = "path") ,
            @ApiImplicitParam(name = "endTime", value = "结束时间：yyyy-MM-dd", required = true, dataType = "String", paramType = "path") 
    )
    @PostMapping("/child")
    public void calc(String createTime,String endTime)  {
        log.info("====================================================");
        log.info("开始xxxx");
        try{
            createTime = createTime + " 00:00:00";
            hisController.fac(createTime);
        }catch (Exception e){
            log.error("/parent/child接口异常",e);
        }

    }

}

5、访问地址

bootstrapui访问地址：http://ip:port/context/doc.html
swagger-ui访问地址：http://ip:port/context/swagger-ui.html