使用Swagger生成在线文档

目录

1：Swagger介绍

2：使用

2.1：swaager集成boot依赖

2.2：配置文件中配置相关信息

2.3：在启动类中加入相关注解

2.4：测试

3：swagger常用注解

1：Swagger介绍

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

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

什么是Swagger？

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

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

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

2：使用

2.1：swaager集成boot依赖

在API工程添加swagger-spring-boot-starter依赖

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

2.2：配置文件中配置相关信息

在引导配置文件 bootstrap.yml中配置swagger的扫描包路径及其它信息，base-package为扫描的包路径，扫描Controller类。

# swagger 文档配置
swagger:
  title: "好课在线系统管理"
  description: "系统管理接口"
  base-package: com.xuecheng.system
  enabled: true
  version: 1.0.0

2.3：在启动类中加入相关注解

在启动类中添加@EnableSwagger2Doc注解

@EnableSwagger2Doc
@SpringBootApplication
public class SystemApplication {

    public static void main(String[] args) {
        SpringApplication.run(SystemApplication.class,args);
    }
}

2.4：测试

启动服务：

 可以看到文档页面已正常显示，但是可读性不是很高，可以使用swaager提供的一些注解来增强接口文档的可读性。

3：swagger常用注解

Swaager的常用注解如下：

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

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

测试使用：

在类中添加注解，在方法上添加注解，增加可读性

@Slf4j
@RestController
@Api(value = "系统字典",tags = "系统字典查询接口")
public class DictionaryController  {

    @Autowired
    private DictionaryService  dictionaryService;
    @ApiOperation("查询所有字典中的信息")
    @GetMapping("/dictionary/all")
    public List<Dictionary> queryAll() {
        return dictionaryService.queryAll();
    }
    @ApiOperation("查询指定编码所对应的详情信息")
    @GetMapping("/dictionary/code/{code}")
    public Dictionary getByCode(@PathVariable String code) {
        return dictionaryService.getByCode(code);
    }
}