奶爸式Swagger教学

目录

一、导入依赖

二、SwaggerConfig基础编程

三、Swagger 常用说明注解

1.@API

2.@ApiOperation

3.@ApiModel

4.ApiModelProperty

5.@ApiParam

6.@ApilmplicitParam

---

一、导入依赖

  <!--开启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 {@Beanpublic Docket webApiConfig() {Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("webApi").apiInfo(apiInfo()).select().paths(Predicates.and(PathSelectors.regex("/api/.*"))).build();return docket;}@Beanpublic 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;
}