Swagger使用小记
Swagger是一种框架,用于自动生成Restfull API的文档,而不用开发者自己编写文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。
以下以SpringBoot 2.0.1中整合Swagger2.8.0为例.
1、Maven:
<!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
2、建立Swagger配置类

@Configuration @EnableSwagger2 public class SwaggerConfig implements WebMvcConfigurer { // 须不能被拦截的资源(包括请求的拦截、返回信息的拦截改造等),如不能被WebSecurity框架拦截 public static final List<String> RESOURCE_PATTERNS = Arrays.asList("/swagger-ui.html", "/webjars/**", "/swagger-resources/**", "/api-docs", "/v2/api-docs"); @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // API文档页面相关资源作为静态资源,以防止被拦截处理 registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); registry.addResourceHandler("/swagger-resources/**").addResourceLocations("classpath:/META-INF/resources/"); } private ApiInfo apiBasicInfo = new ApiInfoBuilder().title("SSEducationAdmin Server API").description("Spring Boot REST API for SSEducationAdmin").version("0.0.1") .license("Apache License Version 2.0").licenseUrl("https://www.apache.org/licenses/LICENSE-2.0\"") .contact(new Contact("San Zhang", "https://localhost:8082/", "zhangsan1@xx.com")).build(); private Parameter tokenHeaderParameter = new ParameterBuilder().name(BasicWebSecurityConfig.AUTHENTICATION_HEADER_NAME).description("接口调用认证及鉴权").modelRef(new ModelRef("string")) .parameterType("header").required(true).build(); //通过Docket进行API分组,通常根据业务模块来分组,这样可在swagger ui上选择这些分组看对应的API @Bean public Docket allApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiBasicInfo).globalOperationParameters(Arrays.asList(tokenHeaderParameter)).groupName("所有接口").select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build(); } @Bean public Docket customerManageApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiBasicInfo).globalOperationParameters(Arrays.asList(tokenHeaderParameter)).groupName("客户管理接口").select() .apis(RequestHandlerSelectors.basePackage(CustomerAdmin_CustomerController.class.getPackage().getName()))// 指定扫描的包,其下Controller方法会生成文档 .paths(PathSelectors.any()).build(); } }
若未配置分组,则默认会将所有 @Controller 修饰的类下的接口都扫描列出来。
需要注意的是:需要将一些swagger用到的接口或资源放行(包括请求的拦截放行、响应信息的拦截放行),相关路径为上述代码中变量 RESOURCE_PATTERNS 的内容( "/swagger-ui.html", "/webjars/**", "/swagger-resources/**", "/api-docs", "/v2/api-docs" ),否则若被拦截通常会报如下错误:
3、Swagger使用:相关注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiParamImplicitL:一个请求参数
- @ApiParamsImplicit 多个请求参数
4、访问
http://localhost:8080/swagger-ui.html:(UI风格)
http://localhost:8080/v2/api-docs:(API风格)
参考资料:
1、SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2
2、https://blog.csdn.net/hu_zhiting/article/details/80462110