SpringBoot集成Swagger文档的配置

Swagger

配置Swagger

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

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

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

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

<dependency>
    <groupId>com.spring4allgroupId>
    <artifactId>swagger-spring-boot-starterartifactId>
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("容器启动成功");
    }
}

你可能感兴趣的:(web基础,spring,boot,后端,java,swagger)