Swagger3.0和Knife4j

原创已于 2022-11-15 17:17:29 修改 · 723 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring #spring boot

于 2022-11-15 17:12:24 首次发布

springcloud 专栏收录该内容

5 篇文章

订阅专栏

本文档展示了如何在Spring Boot项目中整合Swagger3和Knife4j，创建详细的API接口文档。通过配置`pom.xml`引入相关依赖，设置` Knife4jConfiguration`和`SwaggerConfig`配置类，以及在`DemoController`和`UserController`中使用`@ApiOperation`注解，实现了接口的文档化。访问Swagger UI和Knife4j接口文档，可以查看和测试接口。

1、pom依赖


    <properties>
        <java.version>1.8</java.version>
        <spring.cloud.alibaba.version>2.2.6.RELEASE</spring.cloud.alibaba.version>
        <spring.boot.version>2.3.12.RELEASE</spring.boot.version>
        <spring.cloud.version>Hoxton.SR12</spring.cloud.version>
    </properties>
    
    <repositories>
        <repository>
            <id>alimaven</id>
            <name>aliyun maven</name>
            <url>https://maven.aliyun.com/nexus/content/repositories/central/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>alimaven</id>
            <name>aliyun maven</name>
            <url>https://maven.aliyun.com/nexus/content/repositories/central/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

 		<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
             <version>2.3.12.RELEASE</version>
        </dependency>
        <!-- SpringBoot整合springfox-swagger3 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!-- knife4j -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>
        <!-- swagger3 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

2、configuration

2.1、Knife4jConfiguration

package org.wuwangfu.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author： jcshen
 * @Date： 2022/11/15
 * @Description：Knife4j
 *
 *  接口文档界面：http://localhost:8080/doc.html#
 */

@Configuration
@EnableKnife4j
public class Knife4jConfiguration {

    //knife
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("Knife4j渲染OpenAPI接口文档")
                        .description("# Knife4j渲染OpenAPI接口文档")
                        //.termsOfServiceUrl("http://www.xx.com/")
                        // .contact(new Contact("jcshen","027","wuwangfu.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("3.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("org.wuwangfu.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

2.2、SwaggerConfig

package org.wuwangfu.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author： jcshen
 * @Date： 2022/11/15
 * @Description：配置Swagger 3.0，网页展示配置
 *
 *  接口文档界面：http://localhost:8080/swagger-ui/index.html
 */


@EnableOpenApi   // 开启Swagger自定义接口文档
@Configuration   // 相当于Spring配置中的<beans>
public class SwaggerConfig {
    @Bean   // 相当于Spring 配置中的<bean>
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    // API基础信息定义（就是更新Swagger默认页面上的信息）
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("Swagger3接口文档")
               // .contact(new Contact("jcshen", "网址", "wuwangfu.com"))
                .version("v1.0")
                .build();
    }


}

3、启动类KnifeApplication

package org.wuwangfu;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author： jcshen
 * @Date： 2022/11/15
 * @Description：
 */

@Slf4j  //日志
@SpringBootApplication  //启动
@EnableSwagger2 //文档配置
public class KnifeApplication {

    public static void main(String[] args) {
        SpringApplication.run(KnifeApplication.class,args);
    }

}

4、entity

package org.wuwangfu.entity;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author： jcshen
 * @Date： 2022/11/15
 * @Description：
 */

@Data
public class UserVO {

    @ApiModelProperty(value = "用户id")
    private String userId;
    @ApiModelProperty(value = "用户名")
    private String userName;
    @ApiModelProperty(value = "用户年龄")
    private Integer userAge;
    @ApiModelProperty(value = "用户密码")
    private String password;
    @ApiModelProperty(value = "手机号")
    private String phone;
    @ApiModelProperty(value = "用户地址")
    private String address;


}

5、controller

5.1、DemoController

package org.wuwangfu.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
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 org.wuwangfu.entity.UserVO;

/**
 * @author： jcshen
 * @Date： 2022/11/15
 * @Description：
 *  接口文档界面：http://localhost:8080/swagger-ui/index.html
 *
 */

@RestController
@RequestMapping("/demo")
@Api(tags = "demo模块")
public class DemoController {

    @GetMapping("/userList")
    @ApiOperation(value = "查询所有的用户信息")
    public UserVO getUserList() {
        UserVO vo = new UserVO();
        vo.setUserId("nihao");
        vo.setUserName("你好");
        vo.setUserAge(18);
        vo.setPassword("123456");
        vo.setPhone("12345612345");
        vo.setAddress("你好你好你好你好你好你好你好");
        return vo;
    }
}

5.2、UserController

package org.wuwangfu.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.wuwangfu.entity.UserVO;

/**
 * @author： jcshen
 * @Date： 2022/11/15
 * @Description：
 *  接口文档界面：http://localhost:8080/doc.html#
 *
 */

@RestController
@RequestMapping("/user")
@Api(tags = "用户模块")
public class UserController {

    @GetMapping("/userList")
    @ApiOperation(value = "查询所有的用户信息")
    public UserVO getUserList() {
        UserVO vo = new UserVO();
        vo.setUserId("nihao");
        vo.setUserName("你好");
        vo.setUserAge(18);
        vo.setPassword("123456");
        vo.setPhone("12345612345");
        vo.setAddress("你好你好你好你好你好你好你好");
        return vo;
    }
}