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注解使用

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

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/