swagger2使用

最新推荐文章于 2024-08-09 07:27:13 发布

漠翊歌

最新推荐文章于 2024-08-09 07:27:13 发布

阅读量242

点赞数

本文链接：https://blog.youkuaiyun.com/qq_34839150/article/details/109845142

版权

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

关于Swagger

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

注意：用 Swagger 文件生成互动的 API 文档是最精简的，它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

Spring Boot集成使用Swagger

创建Spring Boot Web工程并且引入Swagger依赖

所需Swagger依赖可以在Maven仓库中找查询

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

创建User实体类

package com.example.demo.domain;

/**
 * @author liu
 * @title: User
 * @projectName demo
 * @description: TODO
 * @date 2019/3/1821:52
 */
public class User {
    private Long id;
    private String username;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", username='" + username + '\'' +
                '}';
    }
}

在启动类目录创建Swagger2配置类

package com.example.demo;

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 Swagger2  {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))//扫描controller下的包
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("swagger2 构建APIS")
                .version("1.0")
                .build();
    }
}

创建UserController类

package com.example.demo.controller;

import com.example.demo.domain.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @author liu
 * @title: HelloController
 * @projectName demo
 * @description: TODO
 * @date 2019/3/1821:48
 */
@RestController
@Api(tags = "用户模块")
@RequestMapping(value = "/user")
public class UserController {
    /**
     * 此处为了方便直接用一个Map来模拟数据库进行操作
     */
    static Map<Long, User> userMap;

    static {
        userMap = new HashMap<>();
        User user = new User();
        user.setId((long) 10000);
        user.setUsername("admin");
        userMap.put((long) 10000,user);
    }

    @ApiOperation(value = "获取用户列表")
    @RequestMapping(value = "list", method = RequestMethod.GET)
    public List<User> getUserList() {

        return new ArrayList<User>(userMap.values());
    }


    @ApiOperation(value = "创建用户")
    @ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "id", dataType = "Long", required = true, value = "用户id", defaultValue = "10001"),
            @ApiImplicitParam(paramType = "query", name = "username", dataType = "String", required = true, value = "用户名字", defaultValue = "菜菜")
    })
    @RequestMapping(value = "", method = RequestMethod.POST)
    public String postUser(User user) {

        userMap.put(user.getId(),user);
        return "添加成功";
    }



    @ApiOperation(value = "获取用户")
    @ApiImplicitParam(paramType = "query", required = true, name = "id", dataType = "Long", value = "用户id")
    @RequestMapping(value = "", method = RequestMethod.GET)
    public User getUser(@RequestParam("id") Long id) {
        System.out.println(id);
        return userMap.get(id);
    }



    @ApiOperation(value = "更新用户")
    @ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "id", dataType = "Long", required = true, value = "用户id", defaultValue = "10001"),
            @ApiImplicitParam(paramType = "query", name = "username", dataType = "String", required = true, value = "用户名字", defaultValue = "菜菜")
    })
    @RequestMapping(value = "", method = RequestMethod.PUT)
    public String putUser(User user) {
        userMap.put(user.getId(),user);
        return "更新成功";
    }


    @ApiOperation(value = "删除用户")
    @ApiImplicitParam(paramType = "query", required = true, name = "id", dataType = "Long", value = "用户id")
    @RequestMapping(value = "", method = RequestMethod.DELETE)
    public String deleteUser(@RequestParam("id") Long id) {
        userMap.remove(id);
        return "删除成功";
    }
}

测试:

主界面:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-OIiqKByA-1605846268510)(/swagger2简介/1.png)]

查询用户列表:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-VS6WO6TG-1605846268511)(/swagger2简介/2.png)]

创建用户:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-PrPD5iEc-1605846268513)(/swagger2简介/3.png)]

获取用户:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-2aboZI7w-1605846268514)(/swagger2简介/4.png)]

删除用户:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-gU2p22WD-1605846268515)(/swagger2简介/5.png)]

使用过程中遇到的问题

(1)java.lang.NumberFormatException: For input string: “”

在使用@ApiModelProperty注解在字段上时，如果字段的类型为Long或是int类型，那么程序启动后，访问swagger-ui.html的页面，程序会报错

java.lang.NumberFormatException: For input string: “”
在swagger的官方文档中介绍是一个bug；可以忽略这个错误，如果看着不爽，可以调整日志的级别

application.yml:

logging:
  level:
    io.swagger.models.parameters.AbstractSerializableParameter: error

(2)@Api()注解中使用tags = ""参数才能改变api名字例如@Api(tags = “用户模块”)

(3)requestparam 和pathvariable区别 :

@PathVariable:从路径路去获取变量,也就是把路径名当作变量例如:

http://localhost:8080/user?id=5

@RequestParam:从请求里面获取参数,例如:

http://localhost:8080/user?5