springboot使用swagger2生成api文档

springboot使用swagger2生成api文档一、为什么要用Swagger2?之前开发项目的时候,需要写API文档,项目小接口少的时候一份word就能简单应付,但是随着项目的API的增加,对API文档的维护工作就会越来越繁琐,为此引入能自动生成

大家好,又见面了,我是你们的朋友全栈君。如果您正在找激活码,请点击查看最新教程,关注关注公众号 “全栈程序员社区” 获取激活教程,可能之前旧版本教程已经失效.最新Idea2022.1教程亲测有效,一键激活。

Jetbrains全系列IDE使用 1年只要46元 售后保障 童叟无欺

一、为什么要用Swagger2?

之前开发项目的时候,需要写API文档,项目小接口少的时候一份word就能简单应付,但是随着项目的API的增加,对API文档的维护工作就会越来越繁琐,为此引入能自动生成RESTful接口文档的Swagger2框架就变得理所当然。

作为一个能够自动生成API文档的框架,其最大的优点有两个:

  1. 接口文档在线能够自动生成,文档随接口变动实时更新,节省维护成本
  2. 支持类似spring RESTful插件那样的在线接口测试,不依赖第三方工具

二、举个例子?

假设现在有一个TestController接口,里面有几个简单的API,通过swagger的注解添加接口描述

@Api(value = "Api-test", description = "测试接口")
@RequestMapping("/test/")
@RestController
public class TestController {
    
    @ApiOperation("获取回复")
    @GetMapping("aiTalk")
    public String test(String str){
        str.replace("吗?","");
        return str;
    }
	
    ... ... //下同,不再赘述
}

启动项目后访问特定页面即可看到以Controller分类的API文档,点击展开以,根据注解的详细程度,会有传入参数,返回类型等详细说明,除此之外,还会有类似springREST插件那样的在线测试功能

springboot使用swagger2生成api文档

三、如何在项目中引入swagger2?

1.引入Maven依赖

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2.在springboot配置使用Swagger

/**
 * @Author:huang
 * @Date:2020-02-23 13:22
 * @Description:配置swagger2
 */
@EnableSwagger2
@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
            .groupName("huangApi")
            .apiInfo(adminApiInfo())
            .select()
            .paths(Predicates.and(PathSelectors.regex("/.*")))
            .build();
    }

    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
            .title("简单课程表-API文档")
            .description("本文档描述了简单课程表系统的接口定义")
            .version("1.0")
            .build();
    }
}

3.访问页面

启动项目,访问 http://localhost:8080/swagger-ui.html#/ 即可

四、swagger2注解

1.@Api注解

用在请求的类上,表示对类的说明

属性 作用
value 描述类的作用
tags 说明该类的作用,非空时将覆盖value的值
protocols 设置特定协议,例:http, https, ws, wss
hidden 默认为false, 配置为true 将在文档中隐藏

实例:

@Api(value = "Api-test", tags = "测试接口")
@RequestMapping("/test/")
@RestController
public class TestController {
    
}

2. @ApiOperation注解

用在请求的方法上,说明方法的用途、作用

属性 作用
value 描述方法的作用
tags 说明该方法的作用,非空时将覆盖value的值
response 返回对象类型(如果该对象类有@ApiModel属性会在文档的Model中列出)
httpMethod 指定HTTP方法,”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
hidden 默认为false, 配置为true 将在文档中隐藏

实例:

@ApiOperation(value = "获取课程表",response = CourseSchedule.class, httpMethod = "GET")
@RequestMapping(method = RequestMethod.GET, path =  "getCourseSchedule")
public CourseSchedule getCourseSchedule(){
    return new CourseSchedule();
}

3. @ApiImplicitParams注解

@ApiImplicitParam注解,用在@ApiImplicitParams注解中,表示一组参数的说明

@ApiParam注解,用在单个参数上,是对单个参数的说明

属性 作用
value 参数的说明
name 参数名,参数名称可以覆盖方法参数名称,路径参数必须与方法参数一致
required 参数是否必须传,默认为false(路径参数必填)
defaultValue 参数的默认值
paramType 参数应该怎么传给接口:
1.“header”对应spring@RequestHeader注解标记的参数;
2.“query”对应spring@RequestParam注解标记的参数;
3.“path”对应spring@PathVariable注解标记的参数;
dataType 参数类型

实例:

@ApiImplicitParams({
    @ApiImplicitParam(name = "str", value = "字符串", required = false, dataType = "String", paramType = "query"),
    @ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer", paramType = "query")
})
@GetMapping(path =  "call")
public Result call(
    @ApiParam(name = "str", value = "字符串", required = false) String str,
    @ApiParam(name = "id", value = "id", required = true) Integer id){
    return Result.success("吱一声以表示项目运行");
}

4. @ApiModel注解

用在请求的类上,表示对类的说明

@ApiModelProperty注解

用在被@ApiModel标记了的类的属性上,用于描述类的属性

注:此注解一般用于响应类上,比如使用@RequestBody注解直接接收对象作为参数的时候,多用于创建或更新

属性 作用
value 此属性的简要说明
name 允许覆盖属性名称
allowableValues 限制参数的可接受值,有以下几种:
1.以逗号分隔的列表
2.范围值
3.设置最小值/最大值
example 属性的示例

实例:

/**
 * @Author:huang
 * @Date:2019-12-11 12:38
 * @Description:考试安排实体类
 */
@ApiModel("考试安排实体类")
public class ExamSchedule{

    @ApiModelProperty("课程名称")
    private String courseName;

    @ApiModelProperty("考场")
    private String examClassroom;

    @ApiModelProperty("考试时间")
    private String examDate;

    @ApiModelProperty("当前时间")
    private String date;

    @ApiModelProperty("当前学期")
    private String nowDate;
}

另外,如果被标记的类有被 @ApiOperation注解的response属性引用的话,在文档页面的Model可以看到

springboot使用swagger2生成api文档

五、使用knife4j对swagger进行增强

1.什么是knife4?

knife4j是为JavaMVC框架集成Swagger生成Api文档的增强解决方案 ,在Swagger的基础上进行了各方面的增强,比如接口排序,一键导出markdown,word,pdf等功能,以及一个逻辑更加清晰而美观的功能,最重要的是,这些实用功能不需要改动任何原有的注释或者代码,只需要加一个依赖!tql!!!

地址: https://doc.xiaominfo.com/

2.简单使用

在原有swagger2依赖下引入knife4j依赖

<!--使用knife4j对swagger进行增强-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.1</version>
</dependency>

然后就可以用了!

没错,原本的 http://localhost:8080/swagger-ui.html#/ 页面访问完全不受影响,但是通过http://localhost:8080/doc.html即可访问knife4j加强后的页面,效果如下:

springboot使用swagger2生成api文档

版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 举报,一经查实,本站将立刻删除。

发布者:全栈程序员-用户IM,转载请注明出处:https://javaforall.cn/170826.html原文链接:https://javaforall.cn

【正版授权,激活自己账号】: Jetbrains全家桶Ide使用,1年售后保障,每天仅需1毛

【官方授权 正版激活】: 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...

(0)


相关推荐

发表回复

您的电子邮箱地址不会被公开。

关注全栈程序员社区公众号