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/

  • 1
    点赞
  • 2
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

码奴生来只知道前进~

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值