Spring Boot中如何使用Swagger详解

Spring Boot中如何使用Swagger详解

目录Swagger 简介配置 Swagger添加依赖为项目开启 Swagger创建 SwaggerConfig 配置类访问 Swagger 前端页面控制器相关注解实体相关注解总结

Swagger 简介

Swagger 是一个方便 API 开发的框架，它有以下优点：

自动生成在线文档，后端开发人员的改动可以立即反映到在线文档，并且不用单独编写接口文档，减轻了开发负担

支持通过 Swagger 页面直接调试接口，方便前端开发人员进行测试

配置 Swagger

Swagger 目前有 2.x 和 3.x 两个主流版本，配置略有不同。

添加依赖

首先去 Maven 仓库中搜索 springfox 查找依赖的坐标，Swagger 是遵循 OpenAPI 规范的技术，而 springfox 是该技术的一种实现，所以这里要搜 springfox 而不是 swagger。

对于 Swagger 2.x，需要在 pom.xml 中添加两项配置：

    io.springfox

    springfox-swagger2

    2.9.2

    io.springfox

    springfox-swagger-ui

    2.9.2

对于 Swagger 3.x，简化了配置项，只需要在 pom.xml 中添加一项配置：

  io.springfox

  springfox-boot-starter

  3.0.0

为项目开启 Swagger

对于 Swagger 2.x，使用 @EnableSwagger2 注解开启 Swagger 功能。

@EnableSwagger2

@SpringBootApplication

public class SwaggerApplication {

    ...

}

对于 Swagger 3.x，使用 @EnableOpenApi 注解开启 Swagger 功能。

@EnableOpenApi

@SpringBootApplication

public class SwaggerApplication {

    ...

}

创建 SwaggerConfig 配置类

对于 Swagger 2.x，实例化 Docket 的时候，需要传入 DocumentationType.SWAGGER_2。

对于 Swagger 3.x，实例化 Docket 的时候，需要传入 DocumentationType.OAS_30。

下面是一份配置模板：

import org.springframework.beans.factory.annotation.Value;

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.*;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

@Configuration

public class SwaggerConfig {

    @Value("${spring.profiles.active:NA}")

    private String active;

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)  // OAS_30

                .enable("dev".equals(active))  // 仅在开发环境开启Swagger

                .apiInfo(apiInfo())

                .host("http://example.com")  // Base URL

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo() {

       &nbshttp://p;return new ApiInfoBuilder()

&nhttp://bsp;               .title("API文档")

                .description("这是描述信息")

                .contact(new Contact("张三", null, null))

                .version("1.0")

                .build();

    }

}

访问 Swagger 前端页面

对于 Swagger 2.x，访问 http://localhost:8080/swagger-ui.html

对于 Swagger 3.x，访问 http://localhost:8080/swagger-ui/

控制器相关注解

@Api：将一个类标记为 Swagger 资源，一般放在 Controller 类上面，通过 tags 指定描述信息，比如 @Api(tags="用户管理")。

@ApiOperation：本注解放在 Controller 方法上面，描述该方法的作用。

@ApiParam：本注解放在 Controller 方法的形参前面，可以描述参数的作用，比如 @ApiParam("用户名") String username。可以使用 value 指定描述信息，通过 required = true 指定必需传递该参数。

package com.example.swagger.controller;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.RestController;

@Api(tags = "Hello控制器")

@RestController

public class HelloController {

    @ApiOperation("展示欢迎信息")

    @GetMapping("/hello")

    public String hello(@ApiParam("名字") String name) {

        return "hello, " + name;

    }

}

实体相关注解

@ApiModel：一般放在实体类上面。可以通过 value 指定别名，不指定时默认为类名。还可以通过 description 指定详细的描述信息。比如 @ApiModel("用户") 就将显示 用户 而不是 User。


如果仅仅想指定描述，而不改变原始类名显示，可以写成 @ApiModel(description = "用户")。

@ApiModelProperty：一般放在实体类的成员变量上面，通过 value 指定描述信息，example 指定示例数据，required = true 指定该参数是必需的，hidden = true 用于隐藏该字段，不会在 API 文档中显示。

package com.example.swagger.pojo;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

import lombok.Data;

@Data

@ApiModel(description = "用户")

public class User {

    @ApiModelProperty("用户名")

    private String username;

    @ApiModelProperty("密码")

    private String password;

    @ApiModelProperty(value = "年龄", example = "18", required = true)

    private int age;

    @ApiModelProperty(hidden = true)

    private double money;

}

总结

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。