Swagger的基本使用

 介绍

在前后端分离开发中通常由后端程序员设计接口，完成后需要编写接口文档，最后将文档交给前端工程师，前端工程师参考文档进行开发。

可以通过一些工具快速生成接口文档 ，例如Swagger生成接口在线文档 。

什么是Swagger？

        OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

（https://github.com/OAI/OpenAPI-Specification）

        Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。 (API Documentation & Design Tools for Teams | Swagger)

Spring Boot 可以集成Swagger，Swaager根据Controller类中的注解生成接口文档 ，只要添加Swagger的依赖和配置信息即可使用它。

使用

首先导入pom

<!-- Spring Boot 集成 swagger -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

在yml配置文件中加入

#http://localhost:63042/content/swagger-ui.html
swagger:
  title: "线上课程平台"
  description: "内容系统管理系统对课程相关信息进行管理"
  base-package: com.example.content
  enabled: true
  version: 1.0.0

在启动类上加注解@EnableSwagger2Doc

@EnableSwagger2Doc
@SpringBootApplication
public class CoursePlatformContentApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(CoursePlatformContentApiApplication.class, args);
    }

}

在浏览器输入 #http://localhost:63042/content/swagger-ui.html 即可进入

 在接口文档中加入标注

只需要在需要标注的字段上加@ApiModelProperty("标注内容")  注解即可

Swagger常用注解

 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiModelProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数

解决乱码

打开settings修改