奶爸式Swagger教学

几两春秋梦_

已于 2023-05-29 19:02:56 修改

阅读量787

点赞数 1

分类专栏：开发文章标签： java 数据库大数据

于 2023-05-12 20:12:19 首次发布

本文链接：https://blog.csdn.net/weixin_64443786/article/details/130649005

版权

开发专栏收录该内容

51 篇文章 0 订阅

订阅专栏

一、导入依赖

  <!--开启Swagger        -->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!-- 引入swagger-ui-layer包 /document.html-->
<!--        访问 http://localhost:8888/document.html-->
        <dependency>
            <groupId>com.zyplayer</groupId>
            <artifactId>swagger-mg-ui</artifactId>
            <version>1.0.6</version>
        </dependency>

二、SwaggerConfig基础编程

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(apiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
        return docket;
    }
    @Bean
    public Docket customApiConfig() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("customApi")
                .apiInfo(customApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/custom/.*")))
                .build();
        return docket;
    }
     private ApiInfo apiInfo() {
     //配置文档信息
        Contact contact = new Contact("**", "184375****@qq.com", "184375****@qq.com");
        return new ApiInfo(
                "管理系统后端接口文档Swagger", // 标题
                "管理系统后端接口", // 描述
                "v1.0", // 版本
                "184375****@qq.com", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
    private ApiInfo customApiInfo() {
        return new ApiInfoBuilder().title("用户功能的API文档")
                .description("本文描述了客户功能的api接口定义")
                .version("1.0")
                .contact(new Contact("***", "", "184375****@qq.com"))
                .build();
    }
}

三、Swagger 常用说明注解

1.@API

是用在Controller类上，表明是swagger资源

拥有两个属性:values、tags

@Api(tags = "管理员最全功能模块")

2.@ApiOperation

是用在Controller方法上，表示一个http请求的操作

value用于方法描述
notes用于提示内容
tags可以重新分组

 @ApiOperation("管理员新增**")

3.@ApiModel

使用场景：在实体类上边使用，标记类时swagger的解析类

案例:

@ApiModel(value="Manager对象", description="管理员")

4.ApiModelProperty

使用场景：使用在被 @ApiModel 注解的模型类的属性上

案例:

    @ApiModelProperty(value = "管理员姓名")
    private String name;

5.@ApiParam

参数描述，用在每个参数前面

@PostMapping("/create")
// 注：这里如果使用 @ApiImplicitParam 会出现无法识别的问题
public Response createMerchants(
        @ApiParam(name = "request", value = "创建商户请求对象") @RequestBody CreateMerchantsRequest request)

6.@ApilmplicitParam

参数描述，可用在方法头

@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "商户ID")
})
@GetMapping("/{id}")
public Response getMerchantsInfo(@PathVariable Integer id) {
    return null;
}