Swagger使用及常见问题

最新推荐文章于 2025-03-20 13:45:32 发布

原创最新推荐文章于 2025-03-20 13:45:32 发布 · 595 阅读

0 ·

CC 4.0 BY-SA版权

文章均为基于日常工作整理而成，如不慎侵权，请联系我进行删除。

文章标签：

#swagger #spring boot #java

随笔专栏收录该内容

16 篇文章

订阅专栏

本文详细介绍如何在SpringBoot项目中集成Swagger2实现API文档自动生成。包括在pom.xml中添加依赖、编写配置文件SwaggerConfig及注解使用等关键步骤，并解决常见问题。

Spring Boot中使用

在pom.xml中注入依赖

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

然后编辑配置文件SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket userApi() {

Predicate<RequestHandler> swaggerSelector = (Predicate<RequestHandler>)RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class);

return new Docket(DocumentationType.SWAGGER_2)
.securitySchemes(newArrayList(new ApiKey[]{this.apiKey()}))
// .securitySchemes(newArrayList(new BasicAuth("test"))) //账号密码登录
// .enable(false) //禁止使用
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage("com.boot"))
.apis(swaggerSelector)
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("**接口")
.description("构建restful api")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.contact("name")
.version("1.0.0")
.build();
}

ApiKey apiKey() {
return new ApiKey("sessionId", "sessionId", "header");
}
}

注解使用

@Api(value = "TestController", description = "**系统", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
public class TestController {
    @ApiOperation(value = "查找所有用户",notes = "注意")
    @ApiImplicitParams({
            @ApiImplicitParam(name="userEmail",value="用户邮箱",dataType="string", paramType = "query",example="test"),
            @ApiImplicitParam(name="display",value="展示",dataType="string", paramType = "query")})
    @GetMapping("/test")
    @ResponseBody
    public Result findAllUser(String userEmail, String display)throws Exception{
    
    }

使用过程中常见问题
1、api接口没有问题，可以用Postman测试成功，但是swagger测试报错，就是注解中的参数paramType没等于query，增加上即可
@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")

2、填写完注解后，在网页上看到每个接口都有GET、POST、DELETE等多种请求方式,要在注解中添加httpMethod = "POST"
@ApiOperation(value = "用户与系统对应关系",httpMethod = "POST")

有的版本写法不一样，有的可能是 method = RequestMethod.GET