一、什么是swagger?
1、是一款书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
二、使用swagger有哪些好处?
1、对于后端人员来说,对参数的增加,删除,修改可直接生成
2、不用手写大量参数,避免错误
三、搭建swagger
1、swagger相关依赖
<!-- 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>
apijar包和swagger的UI界面
2、swagger config
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台 APIs")
.description("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台")
.termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin")
.contact("")
.version("1.0")
.build();
}
}
四、swagger应用
1、API声明
//controller的功能描述
@Api(value = "pet", description = "the pet API")
public interface PetApi {
//option的value的内容是这个method的描述,notes是详细描述,response是最终返回的json model。其他可以忽略
@ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = {
@Authorization(value = "petstore_auth", scopes = {
@AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@AuthorizationScope(scope = "read:pets", description = "read your pets")
})
}, tags={ "pet", })
//这里是显示你可能返回的http状态,以及原因。
@ApiResponses(value = {
@ApiResponse(code = 405, message = "Invalid input", response = Void.class) })
@RequestMapping(value = "/pet",
produces = { "application/xml", "application/json" },
consumes = { "application/json", "application/xml" },
method = RequestMethod.POST)
ResponseEntity<Void> addPet(
//这里是针对每个参数的描述
@ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body);
2、设定API路由
在配置文件重,可设定API路由
springfox.documentation.swagger.v2.path: /api-docs
API 显示路由是:http://localhost:8080/swagger-ui.html
五、swagger常用API
1、API注解
@Api(value = "/user", description = "Operations about user")
2、ApiOperation注解
@ApiOperation(
value = "Find purchase order by ID",
notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
response = Order,
tags = {"Pet Store"})
3、ApiParam注解
@ApiParam(value = "Created user object", required = true)