Swagger在springboot中的配置和使用

思行学Java

已于 2023-08-26 04:46:58 修改

阅读量314

点赞数

分类专栏： SpringBoot 文章标签： spring boot java 后端

于 2023-08-26 04:41:05 首次发布

本文链接：https://blog.csdn.net/qq_41764657/article/details/132507127

版权

SpringBoot 专栏收录该内容

5 篇文章 0 订阅

订阅专栏

一、什么是Swagger?有什么用？

Swagger可以自动生成和更新api接口文档，开发可以在线测试接口，其他调用者，如前端也可以直接在这里调用接口，这样开发就不用再手动费力写接口文档了。

如今Swagger最新版本是3.0.0，更新时间是2020年，很久没有更新了，可以有其他好的替代品。

二、Swagger的使用

1、引入pom依赖

经测试，Swagger2.9.2和springboot2.5.6是兼容的。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.6</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger</name>
    <description>swagger</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

2、自定义Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo()是构建api文档的详细信息的方法
                .apiInfo(apiInfo())
                .select()
                //指定要生成api接口的包路径，一般是controller
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     *构建api文档
     *@param
     *@return
    **/
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //设置页面标题
                .title("SpringBoot集成swagger接口总览")
                //设置接口描述
                .description("有各种各样的接口")
                //设置联系方式
                .contact("思行,"+"135xxx")
                //设置版本
                .version("1.0")
                //构建
                .build();
    }

}

启动项目，浏览器输入http://localhost:8080/swagger-ui.html

3、自定义User

@Getter
@Setter
@ToString
@AllArgsConstructor
@ApiModel(value = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户唯一标识")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;

}

4、自定义统一的json返回结构

public class JsonResult<T> {

    private T data;
    private String code;

    private String msg;

    /**
     *若没有数据返回，默认状态是0，提示信息是：操作成功！
    **/
    public JsonResult(){
        this.code="0";
        this.msg="操作成功！";
    }

    /**
     *若没有数据返回，可以人为指定状态和提示信息
     *@param 
     *@return
    **/
    public JsonResult(String code, String msg){
        this.code = code;
        this.msg = msg;
    }

    /**
     *有数据返回，状态码为0，提示信息为：操作成功
    **/
    public JsonResult(T data){
        this.data=data;
        this.code="0";
        this.msg="操作成功";
    }

    /**
     *有数据返回，状态码为0，手动设置提示信息
    **/
    public JsonResult(T data, String msg){
        this.data= data;
        this.code= "0";
        this.msg= msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }
}

5、自定义controller

SwaggerController

@RestController
@RequestMapping("swagger")
//@Api没生效，显示接口名称是默认的接口名：swaggerController
//@Api(value = "Swagger2在线接口文档")
//@ApiOperation无效，只能作用在方法上。
public class SwaggerController {

    @GetMapping("user/{id}")
    //接口文档名称说明
    @ApiOperation(value = "根据用户唯一id获取用户信息")
    //@ApiParam 传入参数说明
    public JsonResult<User> getUser(@PathVariable @ApiParam(value = "用户唯一标识") Integer id){
        User user = new User(id,"张三","123456");
        return new JsonResult<>(user);
    }

    /**
     *添加用户
     *@param
     *@return
    **/
    @PostMapping("insert")
    @ApiOperation(value = "添加用户信息")
    public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user){
        return new JsonResult<>();
    }

}

UserController

@RestController
@RequestMapping("user")
//@Api(value = "用户接口") 无效
public class UserController {

    //如果使用@RequestMapping，swagger会显示get、put、post、delete等各种各样同名的api方法。
    @GetMapping("getUser/{id}")
    @ApiOperation(value = "查询一名用户")
    public User getUser(@PathVariable @ApiParam(value = "用户id") Integer id){
        return new User(id,"王五","1234");
    }
}

6、测试

浏览器输入：http://localhost:8080/swagger-ui.html

测试添加一条用户消息，前端向后端传入一个user对象。

点击/swagger/insert方法，点击 try it out，在example value里输入user对象，再点击excute，皆可以完成user对象的传输。

三、遇到的问题

1、Parameter 0 of method linkDiscoverers in org.springframework.hateoas.config.HateoasConfiguration req错误。

原因：springboot和swagger版本不兼容。

Springboot 2.5.6 和 swagger 2.9.2 是兼容的。

2、NumberFormatException

刷新浏览器时会产生，但不影响代码运行，不用管。

3、如果接口方法使用@RequestMapping注解，会产生很多同名的get、put等方法，算是一个bug，写具体的接口方法注解就只显示该条接口方法，如@GetMapping。

思行学Java

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Swagger在springboot中的配置和使用

Bean//apiInfo()是构建api文档的详细信息的方法.select()//指定要生成api接口的包路径，一般是controller.build();/***构建api文档*@param*@return**///设置页面标题.title("SpringBoot集成swagger接口总览")//设置接口描述.description("有各种各样的接口")//设置联系方式.contact("思行,"+"135xxx")//设置版本//构建.build();
复制链接

扫一扫