添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
定义
@Api(tags = "测试管理/hello")
@RestController
@RequestMapping("/hello")
@RefreshScope
public class Hello {
@ApiOperation(value = "接口简称",notes = "接口描述")
@ApiImplicitParams({
//paramType定义参数传递类型:有path,query,body,form,header
@ApiImplicitParam(name = "token", value = "token", required = true, paramType = "header"),
@ApiImplicitParam(name = "username",value = "用户名",required = true, paramType = "query"),
@ApiImplicitParam(name = "password", value = "密码", required = true, paramType = "query")
})
@ApiResponses({
@ApiResponse(code=200,message = "调用成功"),
@ApiResponse(code=401,message = "无权限")
})
@GetMapping("/swaggers")
public String swaggers(@RequestParam String username, @RequestParam String password) {
return "ok"+ username + password;
}
}
配置类
package com.example.web1_2.swegger;
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;
/**
* @Api: 用于类,标识这个类是swagger的资源
* @ApiIgnore: 用于类,忽略该 Controller,指不对当前类做扫描
* @ApiOperation: 用于方法,描述 Controller类中的 method接口
* @ApiParam: 用于参数,单个参数描述,与 @ApiImplicitParam不同的是,他是写在参数左侧的。如( @ApiParam(name="username",value="用户名")Stringusername)
* @ApiModel: 用于类,表示对类进行说明,用于参数用实体类接收
* @ApiProperty:用于方法,字段,表示对model属性的说明或者数据操作更改
* @ApiImplicitParam: 用于方法,表示单独的请求参数
* @ApiImplicitParams: 用于方法,包含多个 @ApiImplicitParam
* @ApiResponse: 用于方法,描述单个出参信息
* @ApiResponses: 用于方法,包含多个@ApiResponse
* @ApiError: 用于方法,接口错误所返回的信息
*
*
* Failed to start bean ‘documentationPluginsBootstrapper‘;解决方法
* 在application.properties里配置里添加:
* spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
* 原因: 这是因为Springfox使用的路径匹配是基于AntPathMatcher的,而Spring Boot 2.6.X使用的是PathPatternMatcher。
*/
@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的,代表swagger2
//.groupName("分布式任务系统") // 如果配置多个文档的时候,那么需要配置groupName来分组标识
.apiInfo(apiInfo()) // 用于生成API信息
.select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
.apis(RequestHandlerSelectors.basePackage("com.example.web1_2.controller")) // 用于指定扫描哪个包下的接口
.paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档,可以配置这里
.build();
}
/**
* 用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试") // 可以用来自定义API的主标题
.description("测试描述") // 可以用来描述整体的API
.termsOfServiceUrl("") // 用于定义服务的域名
.version("1.0") // 可以用来定义版本。
.build(); //
}
}
导出文件
运行中根目录执行 mvn swagger2markup:convertSwagger2markup
<build>
<plugins>
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
<!-- api-docs访问url -->
<swaggerInput>http://localhost:40012/v2/api-docs</swaggerInput>
<!-- 生成为单个文档,输出路径
<outputFile>src/main/doc/api</outputFile>-->
<!-- 生成为多个文档,输出路径 -->
<outputDir>src/main/resources/ui</outputDir>
<config>
<!-- wiki格式文档 -->
<!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage> -->
<!-- ascii格式文档 -->
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<!-- markdown格式文档 -->
<!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
</config>
</configuration>
</plugin>
</plugins>
</build>