swagger语法

大纲

Swagger介绍knife4j介绍SpringBoot整合knife4jSpringBoot整合knife4j-添加maven依赖SpringBoot整合knife4j-配置SwaggerSpringBoot整合knife4j-设置静态资源映射SpringBoot整合knife4j-访问Swagger UISwagger常用注解介绍@Api注解@ApiOperation@ApiParam@ApiModel@ApiModelProperty@ApiIgnore

Swagger介绍

Swagger是一种用于构建、文档化Web服务的工具集。它包括一组开源软件工具，可以快速而准确地创建高质量API文档，并且可以自动生成客户端代码以及服务端的框架代码。

Swagger最初是由Tony Tam在2010年创建的。自那以后，它已经成为了一种流行的规范，广泛用于构建RESTful Web服务的API文档。与其他Web服务框架相比，Swagger的优点包括：

• API文档化：Swagger可以生成API文档，让我们可以直接查看API的结构、请求参数和响应结果等详细信息。这对于开发者来说非常有帮助，可以快速了解API的使用方法和要求，使得前后端分离开发更加方便，有利于团队协作。

• 客户端生成：Swagger可以根据API文档自动生成客户端代码，使得客户端开发人员可以方便地调用API，无需手动编写请求和解析响应。

• 服务端生成：Swagger还可以根据API文档自动生成服务端的框架代码，可以减少开发人员的工作量，提高生产效率。

• 跨语言支持：Swagger支持多种语言和框架，可以适应不同的开发环境，方便多团队协作开发。

总之，Swagger是一种非常强大的工具，可以大大简化Web服务的开发和维护，提高团队的生产效率。需要注意的是，Swagger只是一种规范和工具集，并不限制我们使用特定的语言或框架。因此，在使用Swagger时，需要结合具体的开发环境和需求，选择合适的实现方式和工具。目前JavaEE开发一般都使用knife4j框架。

knife4j介绍

Knife4j是开源的API文档工具，它基于Swagger UI进行二次开发，并提供了一些额外的功能和扩展，以便更好地展示和管理API文档。

与Swagger UI相比，Knife4j的优点在于：

• 更丰富的UI界面：Knife4j提供了一些额外的UI组件和样式，使得API文档更加易于阅读和理解。例如，可以为API接口添加描述信息、请求示例、响应示例等内容，以便用户更好地了解API的使用方法。

• 更多的功能扩展：Knife4j支持独立部署，可以方便地将API文档与应用程序分开管理。此外，Knife4j还提供了在线调试、Mock数据生成、权限控制等功能，使得API文档的构建和管理变得更加简单和高效。

• 更好的兼容性：Knife4j对Swagger规范进行了良好的支持，可以与各种后端框架和编程语言进行集成。此外，Knife4j还支持OpenAPI规范，可以方便地与其他API工具进行集成。

总之，Knife4j是一种非常强大而灵活的API文档工具，可以帮助我们快速构建高质量的API文档，并提供诸如在线调试、Mock数据生成等附加功能。如果您需要构建API文档，不妨考虑使用Knife4j。目前JavaEE开发一般都使用knife4j框架。

SpringBoot整合knife4j

以下是Spring Boot整合Knife4j的详细流程:

1. 添加maven依赖

2. 配置Swagger

3. 设置静态资源映射

4. 访问Swagger UI

SpringBoot整合knife4j-添加maven依赖

在pom.xml文件中，添加Knife4j在Spring Boot框架下的starter起步依赖。

<!-- swagger knife4j -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

SpringBoot整合knife4j-配置Swagger

在Spring Boot应用程序中，可以通过配置类的方式配置Swagger。创建WebMvcConfiguration类集成WebMvcConfigurationSupport，配置如下：

package com.cxypa.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/**
 * @author 程序员平安
 * 公众号 程序员平安
 * 网站 cxypa.com
 */

// 配置类
@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        // 创建ApiInfo对象设置API的基本信息，例如标题、描述和版本号等
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("员工管理系统接口文档")
                .version("1.0")
                .description("SpringBoot集成Swagger接口文档")
                .build();

        // 创建一个Docket对象，代表一个API文档构建器
        // 通过apiInfo()方法设置API的基本信息
        // 通过select()方法指定需要扫描的控制器包路径，这里指定的包路径是`com.cxypa.controller`
        // 最后，通过build()方法生成Docket对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cxypa.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

上面的代码中，创建一个Docket对象，代表一个API文档构建器。通过调用apiInfo()方法设置API的基本信息，例如标题、描述和版本号等。然后，通过select()方法指定需要扫描的控制器包路径，这里是com.cxypa.controller。最后，通过build()方法生成Docket对象。

SpringBoot整合knife4j-设置静态资源映射

package com.cxypa.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/**
 * @author 程序员平安
 * 公众号 程序员平安
 * 网站 cxypa.com
 */

// 配置类
@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        // 创建ApiInfo对象设置API的基本信息，例如标题、描述和版本号等
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("员工管理系统接口文档")
                .version("1.0")
                .description("SpringBoot集成Swagger接口文档")
                .build();

        // 创建一个Docket对象，代表一个API文档构建器
        // 通过apiInfo()方法设置API的基本信息
        // 通过select()方法指定需要扫描的控制器包路径，这里指定的包路径是`com.cxypa.controller`
        // 最后，通过build()方法生成Docket对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cxypa.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 设置静态资源映射, 放行swagger静态资源
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

SpringBoot整合knife4j-访问Swagger UI

在浏览器中输入地址：http://localhost:port/doc.html (port是你自己项目设定的端口号，默认为8080) 即可访问Swagger UI页面。当前项目使用默认端口号8080，访问http://localhost:8080/doc.html，效果如下：

查看API接口文档，效果如下：

测试GET请求的API接口，效果如下：

测试POST请求的API接口，需要设置请求参数，效果如下：

以上就是Spring Boot整合Knife4j的详细流程，如果需要构建API文档并希望添加更多的UI组件和功能扩展，可以考虑使用Knife4j。

Swagger常用注解介绍

在使用Swagger构建API文档时，可以通过使用一些注解来配置API接口的信息和属性，增加接口文档的可读性。下面是Swagger常用的注解及其用法：

@Api注解

用于描述整个API接口的信息，包括名称、描述等。可以添加在Controller类上。

@Api(tags = "员工相关接口", description = "用于员工相关的操作")
@RestController
@RequestMapping("/emps")
public class EmpController {
    @Autowired
    private EmpService empService;
    // 省略其他...
}

使用@Api注解后，原本显示emp-controller变成员工相关接口，效果如下：

@ApiOperation

用于描述单个接口的信息，包括名称、描述、请求方法等。可以添加在具体的接口方法上。

@Api(tags = "员工相关接口", description = "用于员工相关的操作")
@RestController
@RequestMapping("/emps")
public class EmpController {
    @Autowired
    private EmpService empService;

    @ApiOperation("查询所有员工")
    @GetMapping()
    public Result getAll() {
        // ...
    }

    @ApiOperation("根据id查询一个员工")
    @GetMapping("/{id}")
    public Result getById(@PathVariable Integer id) {
        // ...
    }

    @ApiOperation("分页查询员工")
    @GetMapping("/page")
    public Result page(String name,
                       Integer gender,
                       @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate begin,
                       @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate end,
                       @RequestParam(defaultValue = "1") Integer page,
                       @RequestParam(defaultValue = "5") Integer pageSize) {
        // ...
    }

    @ApiOperation("添加员工")
    @PostMapping
    public Result save(@RequestBody Emp emp) {
        // ...
    }

    @ApiOperation("根据id修改员工")
    @PutMapping
    public Result update(@RequestBody Emp emp) {
        // ...
    }

    @ApiOperation("根据id删除一个员工")
    @DeleteMapping("/{id}")
    public Result deleteById(@PathVariable Integer id) {
        // ...
    }

    @ApiOperation("根据id批量删除员工")
    @DeleteMapping("/deleteBatch/{ids}")
    public Result deleteBatch(@PathVariable List<Integer> ids) {
        // ...
    }
}

使用@ApiOperation注解后，原本显示方法名变成注解的说明，效果如下：

@ApiParam

用于描述接口参数的信息，包括名称、类型、描述等。可以添加在接口方法的参数上。

@ApiOperation("根据id查询一个员工")
@GetMapping("/{id}")
public Result getById(@PathVariable @ApiParam("员工id") Integer id) {
    // 调用业务层根据id查询员工
    Emp emp = empService.getById(id);

    // 响应数据
    return Result.success(emp);
}

使用@ApiParam注解后，参数说明变成注解指定参数说明，效果如下：

@ApiModel

用于描述数据模型的信息，包括名称、描述等。可以添加在实体类上。

package com.cxypa.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDate;
import java.time.LocalDateTime;

// 员工实体类
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户实体类")
public class Emp {
    // ...
}

使用@ApiModel注解后，参数说明变成注解指定参数说明，效果如下：

@ApiModelProperty

用于描述数据模型属性的信息，包括名称、类型、描述等。可以添加在实体类的属性上。

package com.cxypa.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDate;
import java.time.LocalDateTime;

/**
 * @author 程序员平安
 * 公众号 程序员平安
 * 网站 cxypa.com
 */

// 员工实体类
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "用户实体类")
public class Emp {
    @ApiModelProperty("员工id")
    private Integer id;                 // 员工id

    @ApiModelProperty("用户名")
    private String empName;             // 用户名

    @ApiModelProperty("密码")
    private String password;            // 密码

    @ApiModelProperty("性别 , 1 男, 2 女")
    private Short gender;               // 性别 , 1 男, 2 女

    @ApiModelProperty("图像url")
    private String imageUrl;            // 图像url

    @ApiModelProperty("职位说明: 1 总经理,2 副总经理, 3 财务总监, 4 财务主管, 5 出纳")
    private Short job;                  // 职位说明: 1 总经理,2 副总经理, 3 财务总监, 4 财务主管, 5 出纳

    @ApiModelProperty("入职日期")
    private LocalDate entrydate;        // 入职日期

    @ApiModelProperty("部门ID")
    private Integer deptId;             // 部门ID

    @ApiModelProperty("创建时间")
    private LocalDateTime createTime;   // 创建时间

    @ApiModelProperty("修改时间")
    private LocalDateTime updateTime;   // 修改时间
}

使用@ApiModel注解后，参数说明变成注解指定参数说明，效果如下：

@ApiIgnore

用于忽略某个接口或参数的文档生成，可以添加在Controller类、接口方法或参数上。

@ApiIgnore
@GetMapping("/ignore")
public String ignore() {
    return "ignore";
}

使用@ApiIgnore注解后，不会在文档中生成响应的API接口。

以上是Swagger常用的注解，在构建API文档时可以根据实际情况使用。通过注解的配置，可以更清晰地描述API接口的信息和属性，使API文档更加完善和易于理解。