Swagger接口文档快速生成

太过爱你忘了你带给我的痛 2022-04-17 05:49 563阅读 0赞

*1.openapi介绍*

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

*2.swagger*

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。

Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>

## 1.swagger常用注解 ##

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

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性：下面是网上从别处找的一张图,

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzk0MjY2_size_16_color_FFFFFF_t_70][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzk0MjY2_size_16_color_FFFFFF_t_70 1][]

2. 定义接口,测试

@Api(value = "页面管理服务端接口",description = "提供了crud的基本操作")
    public interface CmsPageControllerApi {
    
        @ApiOperation("分类查询接口")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "page",required = true,value = "页码",paramType = "path",dataType = "int")
        })
        public QueryResponseResult queryCmsPage(QueryPageRequest request,int size,int page);
    }

在QueryPageRequest类中使用注解 ApiModelProperty 对属性注释：

public class QueryPageRequest extends RequestData {
    
    //    站点id
        @ApiModelProperty("站点id")
        private String siteId;
    }

## Swagger接口测试 ##

Swagger接口生成工作原理：

1、系统启动，扫描到api工程中的Swagger2Configuration类

2、在此类中指定了包路径com.test，找到在此包下及子包下标记有@RestController注解的controller类

3、根据controller类中的Swagger注解生成接口文档。

配置类代码

用的时候直接拷贝就行....

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    //
    @Configuration
    @EnableSwagger2
    public class Swagger2Configuration {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.test"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("学成网api文档")
                    .description("学成网api文档")
    //                .termsOfServiceUrl("/")
                    .version("1.0")
                    .build();
        }
    
    }

启动服务,查看接口文档

正常启动服务,然后访问地址

[http://ip:port/swagger-ui.html][http_ip_port_swagger-ui.html]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzk0MjY2_size_16_color_FFFFFF_t_70]: /images/20220417/538b3dfcd7604475922d66745b56e141.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwNzk0MjY2_size_16_color_FFFFFF_t_70 1]: /images/20220417/fd81c9b4a4cd466d99c61aafe30ab3c5.png
[http_ip_port_swagger-ui.html]: http://localhost:31001/swagger-ui.html