springboot综合项目练习七使用swagger实现接口api文档开发

一. 背景介绍
OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程.
现在很多互联网的项目都是使用前后端分离开发模式,所以对于后端开发人员来说,需要找到一个方式实现接口的快速测试和api文档交付.

二. 目标需求
使用springboot 集成 Swagger，生成Swagger接口,实现后端接口开发后的快速测试和与前端开发实现api文档的快速交接,

三. Swagger概述
Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。 (https://swagger.io/)
Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。
Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述 @ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

四. 代码实现

添加坐标

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2.新建swagger的config类Swagger2Configuration.java

//swagger api起始页 http://localhost:31001/swagger-ui.html
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chen"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("综合练习api文档")
                .description("综合练习api文档")
//                .termsOfServiceUrl("/")
                .version("1.0")
                .build();
    }
}

3.新建一个api接口,使用swagger的标签对接口进行注解说明

@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public interface CmsPageControllerApi {

    //查询全部
    @ApiOperation("查询全部")
    public QueryResponseResult findAll();

    //页面查询
    @ApiOperation("分页查询页面列表")
    @ApiImplicitParams({@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"),@ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")
    })
    public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}

4.创建controller类实现上面api接口

@RestController
@RequestMapping("/cms/page")
public class PageController implements CmsPageControllerApi {

    @Autowired
    CmsPageService pageService;

    @Override
    @GetMapping("/findAll")
    public QueryResponseResult findAll() {
        return pageService.findAll();
    }

    @Override
    @GetMapping("/list/{page}/{size}")
    public QueryResponseResult findList(@PathVariable("page") int page, @PathVariable("size")int size, QueryPageRequest queryPageRequest) {
        //调用service
        return pageService.findList(page,size,queryPageRequest);
    }
}

如果我们使用了spring的自动封装参数功能,将参数封装成bean,如果我们想在api中对参数字段注解,可以在这个bean类的参数上使用@ApiModelProperty注解说明

public class QueryPageRequest {
    //接收页面查询的查询条件
    //站点id
    @ApiModelProperty("站点id")
    private String siteId;
    //页面ID
    @ApiModelProperty("页面ID")
    private String pageId;
    //页面名称
    @ApiModelProperty("页面名称")
    private String pageName;
    //别名
    @ApiModelProperty("别名")
    private String pageAliase;
    //模版id
    @ApiModelProperty("模版id")
    private String templateId;
}

6.最后,启动项目,输入项目地址/swagger-ui.html打开swagger生成的api文档页面,输入参数,点击后面的 Try it out! 按钮就可以看到接口调用结果
在这里插入图片描述

springboot综合项目练习七使用swagger实现接口api文档开发

猜你喜欢