本文最后更新于 2023-10-12，文章内容可能已经过时,请注意内容的辨别。

swagger2

简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

发展原因

在一些大型的项目当中，前后端也分离了，接口非常的多并且会伴随着改动，原来是前端和后端开会定接口，然后分别开发的，但是这样的话会产生时间或者说是扯皮的各种非开发的成本，所以swagger就出现了，通常意义上上他就是一个节约前后端沟通成本的一个工具

使用

1.导入依赖

 <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.配置bean

package kj08.swaggerdemo.conf;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

//api接口包扫描路径
public static final String SWAGGER_SCAN_BASE_PACKAGE = "kj08.swaggerdemo.controller";

public static final String VERSION = "1.0.0";

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
            .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
            .build();
}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("接口调用文档") //设置文档的标题
            .description("随便设置") // 设置文档的描述
            .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
            .termsOfServiceUrl("http://www.baidu.com") //这里配置的是服务网站
            .build();
}
}

3.在controller上面加对应注解

package kj08.swaggerdemo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@Api(description = "学生模块接口")
@RestController
@RequestMapping("/stu")
public class StudentController {





@ApiOperation(value="登录", notes="登录", produces="application/json")
@RequestMapping(value="/login", method= RequestMethod.POST)
public String login(@RequestParam String user, @RequestParam String pwd) {


    return "SUCESS";
}


}

4.访问http://localhost:8080/swagger-ui.html

相关注解

@Api ：请求类的说明

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"

举例

@Api(tags = "账户相关模块")
@RestController
@RequestMapping("/api/account")
public class AccountController {
    //TODO
}

@ApiOperation：方法的说明

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

举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
        @RequestBody @Valid PasswordModel passwordModel) {
    //TODO
}

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

举例：

@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
                        @RequestParam Integer age){
    //TODO
    return AjaxResult.OK();
}

@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
    //TODO
}

@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

举例

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
        @RequestBody @Valid PasswordModel passwordModel) {
    //TODO
}

@ApiModel：用于JavaBean上面，表示一个JavaBean

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
    （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiI

@ApiModelProperty：用在JavaBean的属性上面，说明属性的含义

举例

@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
    @ApiModelProperty("账户Id")
    private String accountId;
//TODO
}

@ApiParam

放在方法参数上面的

name	String	“”	参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
value	String	“”	参数简单描述
defaultValue	String	“”	描述参数默认值
allowableValues	String	“”	可接收参数值限制，有三种方式,取值列表，取值范围
required	boolean	false	是否为必传参数, false:非必传; true:必传
access	String	“”	参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
allowMultiple	boolean	false	指定参数是否可以通过多次出现来接收多个值
hidden	boolean	false	隐藏参数列表中的参数
example	String	“”	非请求体(body)类型的单个参数示例
examples	Example	@Example(value = @ExampleProperty(mediaType = “”, value = “”))	参数示例，仅适用于请求体类型的请求
type	String	“”	添加覆盖检测到类型的功能
format	String	“”	添加提供自定义format格式的功能
allowEmptyValue	boolean	false	添加将格式设置为空的功能
readOnly	boolean	false	添加被指定为只读的能力
collectionFormat	String	“”	添加使用 array 类型覆盖 collectionFormat 的功能

@ApiIgnore

@ApiIgnore 可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。

导入postman

将ui页面的api-docs复制

打开postman-->import-->import Form Link