美文网首页
SpringBoot 使用Swagger文档

SpringBoot 使用Swagger文档

作者: 月弦 | 来源:发表于2019-09-27 16:07 被阅读0次

    前言

    Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

    1、pom.xml文件

    添加swagger2和swagger-ui依赖。

        <properties>
        <java.version>1.8</java.version>
        <swagger.version>2.9.2</swagger.version>
    </properties>

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

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

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!--swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

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

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

    2、配置文件

    和整合jpa一样。

    server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test?serverTimezone=GMT
    username: root
    password: 123456
    driver-class-name: com.mysql.jdbc.Driver
  jpa:
    properties:
      hibernate:
        hbm2ddl:
          auto: update
        dialect: org.hibernate.dialect.MySQL5InnoDBDialect
    show-sql: true

    3、swagger2文档信息配置

    文档信息配置，Swagger 还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息，通过创建一个 ApiInfo 对象，并且使用 Docket.appInfo() 方法来设置。

    @Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.huzh.springbootswagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("spring-boot-demo")
                .description("这是一个简单的 Swagger API 演示")
                .contact(new Contact("企鹅十五号", "https://www.jianshu.com/u/cd874c9edf31", "*****@qq.com"))
                .version("1.0.0-SNAPSHOT")
                .build();
    }
}

    4、实体类

    实体描述，我们可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述。

    @Entity
@ApiModel(description = "用户实体")
public class User {

    @ApiModelProperty(value = "主键id", hidden = true)
    @GeneratedValue
    @Id
    Integer id;

    @ApiModelProperty(value = "用户名称")
    @NotNull
    @Column
    private String username;

    @ApiModelProperty(value = "用户密码")
    @Column
    private String password;

    public Integer getId() {
        return id;
    }

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

    public String getUsername() {
        return username;
    }

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

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public User() {
    }

    public User(Integer id, @NotNull String username, String password) {
        this.id = id;
        this.username = username;
        this.password = password;
    }

    public User(@NotNull String username, String password) {
        this.username = username;
        this.password = password;
    }
}

    5、repository类

    public interface UserRepository extends JpaRepository<User, Integer> {
    User findById(int id);
}

    6、controller类

    1. 通过在控制器类上增加@Api 注解，可以给控制器增加描述和标签信息。
    2. 通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述。
    @RestController
@RequestMapping("/user")
@Api(tags = "用户操作接口", description = "提供用户相关的 Rest API")
public class UserController {
    @Autowired
    UserRepository userRepository;

    @ApiOperation(value = "获取用户详细信息", notes = "根据用户的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "Integer")
    @GetMapping(value = "/findById")
    public User findById(@RequestParam(value = "id") int id) {
        User user = userRepository.findById(id);
        return user;
    }

    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    @GetMapping(value = "/getUserList")
    public List getUserList() {
        return userRepository.findAll();
    }

    @ApiOperation(value = "保存用户", notes = "保存用户")
    @PostMapping(value = "/saveUser")
    public String saveUser(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) User user) {
        userRepository.save(user);
        return "success!";
    }

    @ApiOperation(value = "修改用户", notes = "修改用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "主键id", required = true, paramType = "query", dataType = "Integer"),
            @ApiImplicitParam(name = "username", value = "用户名称", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "password", value = "用户密码", required = true, paramType = "query", dataType = "String")
    })
    @GetMapping(value = "/updateUser")
    public String updateUser(@RequestParam(value = "id") int id, @RequestParam(value = "username") String username,
                             @RequestParam(value = "password") String password) {
        User user = new User(id, username, password);
        userRepository.save(user);
        return "success!";
    }

    @ApiOperation(value = "删除用户", notes = "根据用户的id来删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "Integer")
    @DeleteMapping(value = "/deleteUserById")
    public String deleteUserById(@RequestParam(value = "id") int id) {
        User user = userRepository.findById(id);
        userRepository.delete(user);
        return "success!";
    }
}

    7、访问验证

    image.png

    8、高级配置

    接口过滤

    有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解，另一种是在 Docket 上增加筛选。

    1. @ApiIgnore 注解。
      如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
    2. 在 Docket 上增加筛选。
      Docket 类提供了 apis() 和 paths()两个方法来帮助我们在不同级别上过滤接口：
      apis()：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描。
      paths()：这种方式可以通过筛选 API 的 url 来进行过滤。

    自定义响应消息

    Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息，但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息，假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息，我们只需要在 Swagger2Config.java 类中的 Docket Bean 下添加如下内容：

                    .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, newArrayList(
                        new ResponseMessageBuilder()
                                .code(500)
                                .message("服务器发生异常")
                                .responseModel(new ModelRef("Error"))
                                .build(),
                        new ResponseMessageBuilder()
                                .code(403)
                                .message("资源不可用")
                                .build()
                ));
    自定义响应消息

    9、Swagger UI 的使用

    接口查看

    SwaggerUI 会以列表的方式展示所有扫描到的接口，初始状态是收缩的，我们只需要点击展开就好，而且会在左边标识接口的请求方式（GET、POST、PUT、DELETE 等等）。 接口查看

    接口调用

    • 点击接口展开后页面右上角的 Try it out 按钮。 image.png
    • SwaggerUI 会给我们自动填充请求参数的数据结构，我们需要做的只是点击 Execute 即可发起调用。 image.png

    Model

    SwaggerUI 会通过我们在实体上使用的 @ApiModel 注解以及@ApiModelProperty 注解来自动补充实体以及其属性的描述和备注。 model

    10、相关注解说明

    Controller 相关注解

    • @Api: 可设置对控制器的描述。
    注解属性 类型 描述
    tags String[] 控制器标签。
    description String 控制器描述（该字段被申明为过期）。

    接口相关注解

    • @ApiOperation: 可设置对接口的描述。
    注解属性 类型 描述
    value String 接口说明。
    notes String 接口发布说明。
    tags Stirng[] 标签。
    response Class<?> 接口返回类型。
    httpMethod String 接口请求方式。
    • @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
    • @ApiImplicitParams: 用于描述接口的非对象参数集。
    • @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。
    注解属性 描述
    paramType 查询参数类型，实际上就是参数放在那里。取值：
    path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。
    query：Query string 的方式传参。
    header：以流的形式提交。
    form：以 Form 表单的形式提交。
    dataType 参数的数据类型。取值：
    Long
    String
    name 参数名字。
    value 参数意义的描述。
    required 是否必填。取值：
    true：必填参数。
    false：非必填参数。

    Model 相关注解

    • @ApiModel: 可设置接口相关实体的描述。
    • @ApiModelProperty: 可设置实体属性的相关描述。
    注解属性 类型 描述
    value String 字段说明。
    name String 重写字段名称。
    dataType Stirng 重写字段类型。
    required boolean 是否必填。
    example Stirng 举例说明。
    hidden boolean 是否在文档中隐藏该字段。
    allowEmptyValue boolean 是否允许为空。
    allowableValues String 该字段允许的值，当我们 API 的某个参数为枚举类型时，使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。

    参考文章

    相关文章

      网友评论

          本文标题：SpringBoot 使用Swagger文档

          本文链接：https://www.haomeiwen.com/subject/xdxhyctx.html

          延伸阅读

          深度阅读

          • 您也可以注册成为美文阅读网的作者，发表您的原创作品、分享您的心情！

          栏目导航

          热点阅读

          关于我们|服务条款|联系我们|SpringBoot 使用Swagger文档|投稿指南|网站地图|RSS订阅|排版工具|手机版

          提供经典美文摘抄,优美散文欣赏,现代诗歌精选,短篇小说,心情随笔,表白情书范文,故事会在线阅读欣赏

          Copyright © 2014-2023 Haomeiwen.com All Rights Reserved. 好美文阅读网 版权所有

          备案信息：桂公网安备 45052102000051号 · 桂ICP备13007215号-3

          本站所收录作品、热点评论等信息部分来源互联网，目的只是为了系统归纳学习和传递资讯

          所有作品版权归原创作者所有，与本站立场无关，如不慎侵犯了你的权益，请联系我们告知，我们将做删除处理！