Swagger2介绍及简单使用

最新推荐文章于 2024-07-04 09:05:13 发布

fly-liuhao

最新推荐文章于 2024-07-04 09:05:13 发布

阅读量996

点赞数

分类专栏： Java 文章标签： swagger2

本文链接：https://blog.csdn.net/Fly_1213/article/details/111184042

版权

Java 专栏收录该内容

13 篇文章 1 订阅

订阅专栏

package cn.edu.tit.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassName: SwaggerConfig
 * @Description: Swagger配置了类
 * @Author: liu-hao
 * @Date: 2020-12-10 10:18
 * @Version: 1.0
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "cn.edu.tit.swagger.controller";
    // 接口文档版本
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于分组功能，也可以不配置
                .groupName("eleprice-service")
                //注册整体api信息
                .apiInfo(apiInfo())
                //swagger功能是否启用，可以通过配置设置，也可以先写死
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("xxx管理系统")
                .description("xxx管理系统API接口文档")
                .contact(new Contact("ZhangSan", "", "xxxxx@163.com"))
                .version(VERSION)
                .build();
    }
}

创建Controller接口

package cn.edu.tit.swagger.controller;

import cn.edu.tit.swagger.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @ClassName: StudentController
 * @Description: 学生服务控制层
 * @Author: liu-hao
 * @Date: 2020-12-10 09:53
 * @Version: 1.0
 **/
@Api(value = "学生服务API接口")
@RestController
@RequestMapping(value = "student")
public class StudentController {

    @Autowired
    StudentService studentService;

    @ApiOperation(value = "获取指定学生ID的姓名")
    @GetMapping(value = "getStudentName")
    public String getStudentName(String id) {
        return studentService.getStudentName(id);
    }

    @ApiOperation(value = "获取指定学生ID的性别")
    @GetMapping("getStudentSex")
    public String getStudentSex(String id) {
        return studentService.getStudentSex(id);
    }

    @ApiOperation(value = "获取指定学生ID的学生年龄")
    @GetMapping("getStudentAge")
    public String getStudentAge(String id) {
        return studentService.getStudentAge(id);
    }

    @ApiOperation(value = "获取指定学生ID的班级姓名")
    @GetMapping("getStudentClazzName")
    public String getStudentClazzName(String id) {
        return studentService.getStudentClazzName(id);
    }
}

创建实体类

package cn.edu.tit.swagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @ClassName: Student
 * @Description: 学生实体类
 * @Author: liu-hao
 * @Date: 2020-12-10 09:36
 * @Version: 1.0
 **/
@ApiModel("学生实体类")
public class Student {
    @ApiModelProperty("学号")
    String id;
    @ApiModelProperty("姓名")
    String name;
    @ApiModelProperty("性别")
    String sex;
    @ApiModelProperty("年龄")
    Integer age;
    @ApiModelProperty("班级名称")
    String clazzName;

    public Student() {
    }

    public Student(String id, String name, String sex, Integer age, String clazzName) {
        this.id = id;
        this.name = name;
        this.sex = sex;
        this.age = age;
        this.clazzName = clazzName;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getClazzName() {
        return clazzName;
    }

    public void setClazzName(String clazzName) {
        this.clazzName = clazzName;
    }
}

运行项目，访问地址

访问地址（修改地址端口以及项目上下文路径）：http://localhost:8888/projectName/swagger-ui.html#/

常用注解介绍

（1）@Api

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

（2）@ApiOperation

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

（3）@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

（4）@ApiResponses、 @ApiResponse

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

（5）@ApiModel、@ApiModelProperty

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

三、高阶使用

根据不同环境决定是否开启Swagger

思路：通过Environment实例获取当前所处环境，进而进行实现

@Bean
public Docket docket(Environment environment) {
    // 获取当前环境 是生产环境 启动swagger
    boolean isProFlag = environment.acceptsProfiles(Profiles.of("pro"));
    System.out.println("is dev environment....===========>" + isProFlag);
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).groupName("bitqian").
        enable(isProFlag). // 是否启动swagger 如果为false，则不能在浏览器中使用swagger
        select().
        apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
        // paths(PathSelectors.ant("/hello/**")).
        build();
}

配置Api文档分组

通过在配置类中新增Bean注入实现

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
} 
@Bean
public Docket docket12() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}

微服务环境使用Swagger

参考博客：使用 Zuul 聚合多个微服务的 Swagger 文档

项目工程：zuul-swagger

获取自定义或指定注解的注释

参考博客： swagger2使用自定义注解生成文档

package com.telek.business.config;

import com.telek.framework.annotation.ActionMapping;
import io.swagger.annotations.ApiOperation;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpMethod;
import org.springframework.stereotype.Component;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;

import java.util.List;

/**
 * @ClassName: ActionMappingOperationBuilderPlugin
 * @Description: 自定义控制层注解扫描
 * @Author: liu-hao
 * @Date: 2020-12-10 17:30
 * @Version: 1.0
 **/
@Component
@Order(Ordered.HIGHEST_PRECEDENCE - 10)
public class ActionMappingOperationBuilderPlugin implements OperationBuilderPlugin {
    @Override
    public void apply(OperationContext context) {
        List<ApiOperation> list = context.findAllAnnotations(ApiOperation.class);
        if (list.size() == 0) {
            List<ActionMapping> explainList = context.findAllAnnotations(ActionMapping.class);
            if (explainList.size() > 0) {
                ActionMapping actionMapping = explainList.get(0);
                context.operationBuilder().summary(actionMapping.serverDesc());//替换默认值
            }
        }

    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }
}

fly-liuhao

关注

0
点赞
踩
9

收藏

觉得还不错? 一键收藏
0
评论
Swagger2介绍及简单使用

目录一、简介二、开始使用三、高阶使用视频资源：一小时掌握Swagger技术一、简介swagger是Restfull Api开发工具，提供接口描述文档及调试功能根据配置自动扫描接口生成接口文档，避免后端接口文档不能及时更新，便于前后端完成联调详细介绍可参看：https://www.jianshu.com/p/349e130e40d5二、开始使用pom引入依赖（1）springfox-swagger2<!-- https://mvnrepository.co
复制链接

扫一扫