SpringBoot集成Swagger文档的配置

Swagger

配置Swagger

OpenAPI规范(OpenAPI Specification)简称OAS是Linux基金会的一个项目,通过定义一种语言用来描述API格式和定义,从而规范RESTful服务开发过程

Swagger是全球最大的OpenAPI规范API开发工具框架,它是一个在线接口文档以及在线接口调试页面的生成工具,帮助前后端开发人员依据接口文档进行开发

第一步: SpringBoot可以集成Swagger, 我们只需要添加Swagger的依赖swagger-spring-boot-starter及其配置文件信息

• Swagger会根据Controller类及其方法或模型类及其属性上的注解生成对应的接口文档,方便开发人员对接口文档的阅读

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

swagger:
  title: "学成在线内容管理系统"
  description: "内容系统管理系统对课程相关信息进行业务管理数据"
  # base-package为包扫描路径，通过扫描Controller类中的注解生成接口文档
  base-package: com.xuecheng.content
  enabled: true
  version: 1.0.0

@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageParams {
    // 默认起始页码
    public static final long DEFAULT_PAGE_CURRENT = 1L;
    // 默认每页记录数
    public static final long DEFAULT_PAGE_SIZE = 10L;

    // 当前页码
    @ApiModelProperty("当前页码")
    private Long pageNo = DEFAULT_PAGE_CURRENT;

    // 当前每页记录数
    @ApiModelProperty("每页记录数")
    private Long pageSize = DEFAULT_PAGE_SIZE;
}

第二步: 使用Swagger提供的常用注解并按照OpenAPI规范去定义接口及接口相关的信息

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

@ApiImplicitParam属性

属性	描述	取值
paramType	查询参数类型	path: 以地址的形式提交数据 query: 直接跟参数完成自动映射赋值 body: 以流的形式提交 仅支持POSTbr/> header: 参数在request headers 里边提交 form: 以form表单的形式提交 仅支持POST
dataType	参数的数据类型 只作为标志说明，并没有实际验证	Long或String
name	接收参数名
value	接收参数的意义描述
required	参数是否必填	true: 必填 false: 非必填
defaultValue	默认值

第三步: 在启动类上添加@EnableSwagger2Doc注解生成Swagger接口文档,然后访问生成的接口文档http://localhost:8080/swagger-ui.html

@Slf4j
@EnableSwagger2Doc
@SpringBootApplication
public class ContentApplication {
    public static void main(String[] args) {
        SpringApplication.run(ContentApplication.class, args);
        log.info("容器启动成功");
    }
}