基于Swagger2实现接口文档

╰半夏微凉° 2022-01-26 04:19 376阅读 0赞

Swagger2是一个开源软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用Restful Web服务。

这是“维基百科”上对于Swagger2的一个介绍，可见Swagger2是属于第三方框架，对标的是Restful风格的API，使用Swagger2生成API文档，避免了传统手工记录的繁琐，也便于保存、整理、查阅和调试API接口。

在SpringBoot项目中引入Swagger2：

*  pom.xml引入对应的依赖

<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>

*  增加SwaggerConfig.java配置文件，在Applcation.java中添加@EnableSwagger2，项目启动时同时加载swagger2

@Configuration
    public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //接口对应包下的类，生成API文档
                .apis(RequestHandlerSelectors.basePackage("io.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                .title("可读小说")
                .description("后台管理系统API文档")
                .termsOfServiceUrl("https://swagger.io/")
                .version("1.0.1")
                .build();
        }
    }

同时利用Swagger2提供的注解对接口进行说明，通过访问http://localhost:8080/swagger-ui.html便可获取到相关API文档。

注解的使用（demo）

@Api(tags="小说信息接口")
    @RestController
    @RequestMapping("/info")
    public class InfoController {
    
        @ApiOperation("添加小说信息")
        @PutMapping("/add")
        private String addInfo(){
            return "success";
        }
    
        @ApiOperation("获取小说信息")
        @GetMapping("/{id}")
        private String getInfo( @ApiParam("小说id") @PathVariable("id")int id){
            return "info" + id;
        }
    }

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hzZjE1NzY4NjE1Mjg0_size_16_color_FFFFFF_t_70][]

> 最后再说说Swagger2的常用注解：

*  @Api：用于类，表示标识这个类是swagger的资源
 *  @ApiOperation：用于方法，表示一个http请求的操作
 *  @ApiParam：用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）
 *  @ApiModel：用于类，表示对数据模型进行说明，用于参数用实体类接收
 *  @ApiModelProperty：用于方法，字段，表示对model属性的说明
 *  @ApiIgnore：用于类，方法，方法参数，对应的将不会被显示到文档里
 *  @ApiImplicitParam：用于方法，作用于非对象参数集
 *  @ApiImplicitParams：用于方法，包含多个 @ApiImplicitParam

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2hzZjE1NzY4NjE1Mjg0_size_16_color_FFFFFF_t_70]: /images/20220126/2255cd7533054d7492907bf230c93ea7.png