Swagger注解使用示例

1、Swagger是什么

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2、Swagger受欢迎的原因

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

• Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
• Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
• Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
• Swagger 有一个强大的社区，里面有许多强悍的贡献者。

 3、引用Swagger相关依赖

/?对应的版本号 可以自己修改 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>

4、创建SwaggerConfig配置类

package com.shucha.deveiface.web.config; import org.springframework.beans.factory.annotation.Value; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; / * @author zhouziqiang */ @Configuration @EnableSwagger2 public class SwaggerConfig { @Value("${swagger.enable:true}") private Boolean swaggerEnable; @Bean public Docket swaggerApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(swaggerEnable) .select() //com.shucha.deveiface.web.controller 就是你控制器的路径 .apis(RequestHandlerSelectors.basePackage("com.shucha.deveiface.web.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("deve-iface-API") .contact(new Contact("你的邮箱名称", "", "你的邮箱地址")) .description("API文档") .version("1.0.0-SNAPSHOT") .build(); } } 

5、Swagger基本注解使用

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiImplicitParam注解使用

6、实际demo

package com.shucha.deveiface.web.controller; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.sdy.common.model.Response; import com.sdy.mvc.controller.BaseController; import com.shucha.deveiface.biz.model.App; import com.shucha.deveiface.biz.model.Module; import com.shucha.deveiface.biz.model.Users; import com.shucha.deveiface.biz.service.ModuleService; import com.shucha.deveiface.biz.service.UsersService; import io.swagger.annotations.*; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.servlet.http.HttpServletRequest; import java.util.List; / * @author tqf * @Description * @Version 1.0 * @since 2020-08-25 14:58 */ @Slf4j @RestController @RequestMapping("/test") @Api(tags = "测试使用控制器") public class TestController extends BaseController { @Autowired UsersService UsersService; @Autowired ModuleService ModuleService; @GetMapping("pagedata") @ApiOperation(value = "测试获取值") @ApiImplicitParams({ @ApiImplicitParam(dataType = "String", name = "id", value = "查询id"), }) public Response pagedata(HttpServletRequest request, Page<App> page)throws Exception{ page.getSize(); List<Users> list = UsersService.list(); for (Users users :list){ users.getId(); } return Response.success(list); } @PostMapping("getdata") @ApiOperation(value = "获取list数据") public Response getData(HttpServletRequest request) throws Exception{ return Response.success(); } } 

启动项目之后你的访问地址加上swagger-ui.html    比如：http://localhost:8080/swagger-ui.html 

7、参考文献

Swagger官网 ：http://swagger.io/

Spring Boot & Swagger UI ： http://fruzenshtein.com/spring-boot-swagger-ui/