Swagger rest API 描述
Posted 亲爱的阿道君
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Swagger rest API 描述相关的知识,希望对你有一定的参考价值。
1 工作原理
使用Spring Boot开发前、后端分离的项目越来越多,而前、后端往往是由不同的开发人员或团队负责。如果后端开发了一些REST接口,如何将这些接口即快速又准确地描述给前端开发人员呢?
Swagger提供了一种自动扫描生成API接口文档的技术实现
2 集成步骤
第一步,添加Maven依赖如下:
<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>
第二步,编写配置类;
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文档") .description("") .termsOfServiceUrl("") .version("1.0") .build(); } }
第三步,编写测试Controller:
@Api(description = "测试")
@RestController @RequestMapping("/demo") public class DemoController { @RequestMapping(value = "/user", method = RequestMethod.GET) public Object getUsers(@ApiParam(value = "名称") @RequestParam(required = false) String name) {
List list = new ArrayList();
list.add(name);
return list;
}
}
启动应用并访问 http://localhost:8080/swagger-ui.html
3 API注解
Swagger还提供了一些@注解用于详细的对API接口进行描述。
@Api:修饰整个类,描述Controller的作用。
@ApiOperation:描述一个类的一个方法,或者说一个接口。
@ApiParam:单个参数描述。
@ApiModel:用对象来接收参数。
@ApiProperty:用对象接收参数时,描述对象的一个字段。
@ApiResponse:HTTP响应其中一个描述。
@ApiResponses:HTTP响应整体描述。
@ApiIgnore:使用该注解忽略这个API。
@ApiError:发生错误返回的信息。
@ApiParamImplicit:一个请求参数。
@ApiParamsImplicit:多个请求参数。
4 安全问题
这种公开的接口API文档一般只用于开发环境,在生产环境下会有一定的安全问题。此时可以通过在Swagger配置类上添加@Profile({"dev"})注解进行控制,这样Swagger只有在dev这个profile下才会生效。
以上是关于Swagger rest API 描述的主要内容,如果未能解决你的问题,请参考以下文章
Django Rest framework Swagger生成api文档
Spring集成Swagger2,提供RestFul API