SpringBoot整合Swagger

 一、Swagger简介

Swagger 是一种 API 文档工具，可以通过生成 API 文档来提高开发者的工作效率，同时也可以提高 API 的可读性和可维护性。Spring Boot 可以与 Swagger 进行整合，以方便生成 API 文档。下面介绍一下如何使用 Spring Boot 整合 Swagger 。

Swagger 文档： Annotations · swagger-api/swagger-core Wiki · GitHub

团队协作：Apifox很不错。具体自己去看官网哈：Apifox - API 文档、调试、Mock、测试一体化协作平台。拥有接口文档管理、接口调试、Mock、自动化测试等功能，接口开发、测试、联调效率，提升 10 倍。最好用的接口文档管理工具，接口自动化测试工具。

---

二、引入 Swagger 依赖：

    	<!-- Swagger -->
        <dependency><!--添加Swagger依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency><!--添加Swagger-UI依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

---

三、application.yml 配置属性

swagger:
  title: 项目标题
  description: 项目描述
  version: 1.0
  terms-of-service-url: http://www.javastack.cn/
  base-package: com.hzs.demo.controller
  // 项目联系人信息
  contact:
    name: 名称
    url: 网址
    email: 邮箱

---

四、创建 Swagger 配置类 SwaggerConfig：

@Getter
@Setter
@Configuration //声明该类为配置类
@EnableSwagger2 //启用Swagger
@ConditionalOnClass(EnableSwagger2.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

    /**
     * API接口包路径
     */
    private String basePackage;

    /**
     * API 页面标题（项目标题）
     */
    private String title;

    /**
     * 项目描述
     */
    private String description;

    /**
     * 服务条款地址
     */
    private String termsOfServiceUrl;

    /**
     * 项目版本号
     */
    private String version;

    /**
     * 联系人
     */
    private Contact contact;

    // Docket 对象配置Swagger
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .version(version)
                .contact(contact)
                .build();
    }

}

---

五、常用注解：

注解名称	使用说明
@Api	描述一个 API 类
@ApiImplicitParam	描述一个请求参数
@ApiImplicitParams	描述一组请求参数
@ApiModel	描述一个返回的对象
@ApiModelProperty	描述一个返回的对象参数
@ApiOperation	描述一个 API 方法
@ApiParam	描述一个方法的参数
@ApiResponse	描述一个请求响应
@ApiResponses	描述一组请求响应

---

六、举例如下：

在web访问层引入Swagger 注解

@Api(description = "测试登录模块")
@RestController
public class HelloController {

    @ApiOperation(value = "登录", httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query")})
    @PostMapping(value = "/login")
    public Object login(@RequestParam("username") String username, @RequestParam("password") String password) {
        HashMap<String, Object> result = new HashMap<>();
        result.put("code", 200);
        result.put("token", "fwefnsdfnfsjdvns23123");
        result.put("msg", "登录成功");
        // ...
        return result;
    }
}

---

七、访问：http://localhost:8080/swagger-ui.html

测试是否成功

---

八、美化 Swagger-Ui 界面

将上面的两个依赖替换成如下即可。

<dependency>

<groupId>com.github.xiaoymin</groupId>

<artifactId>knife4j-spring-boot-starter</artifactId>

<version>3.0.2</version>

</dependency>

技术水平有限，如有错误，欢迎指正！