Swagger使用

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格 式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。 （https://github.com/OAI/OpenAPI-Specification） Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周 期的开发。 (https://swagger.io/) Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建 项目的框架。

● 导入Swagger依赖

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

● 定义Swagger配置类。@EnableSwagger2是开启Swagger的注解

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        List<Parameter> params = new ArrayList<>();
        ParameterBuilder authParam = new ParameterBuilder();
        authParam.name(Auth.AUTHENTICATION).description("登录token")
                .modelRef(new ModelRef("string")).parameterType("header")
                //header中的ticket参数非必填，传空也可以
                .required(false).build();
        //根据每个方法名也知道当前方法在设置什么参数
        params.add(authParam.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //扫描com.lbh360下所有带@RestController的类
                .apis(RequestHandlerSelectors.basePackage("com.lbh360"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(params);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("lbh360接口文档")
                .description("连百合接口文档")
//                .termsOfServiceUrl("/")
                .version("1.0")
                .build();
    }

}

● 定义接口使用Swagger提供的注解

@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public interface CmsPageControllerApi {
    @ApiOperation("分页查询页面列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"),
            @ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")
    })
            public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}

● Controller实现接口

public class CmsPageController implements CmsPageControllerApi

● 模型类使用使用Swagger提供的注解

@Data
public class QueryPageRequest extends RequestData {
    @ApiModelProperty("站点id")
    private String siteId;
    @ApiModelProperty("页面ID")
    private String pageId;
    @ApiModelProperty("页面名称")
    private String pageName;
    @ApiModelProperty("别名")
    private String pageAliase;
    @ApiModelProperty("模版id")
    private String templateId;
}

● 测试Swaggger。访问根路径下的swagger-ui.html

 

注意：

1.在用到swagger的工程中一定不能有继承WebMvcConfigurationSupport的拦截器，否则会404。可以改实现WebMvcConfigurer

2.启动类必须放在com.viuman根目录下，否则swagger访问不了，会一直弹窗