SpringBoot2整合Swagger2

1、pom添加依赖

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

2、创建swagger的配置类，注意：与项目启动类同级

package com.jsyl.stfw.mail.fwmail;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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 Swagger2 extends WebMvcConfigurationSupport{
    //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.mail.fwmail.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("RESTful API接口示例")
                //创建人
                .contact("Pagegle李")
//                .contact(new Contact("李", "http://www.baidu.com", ""))
                //版本号
                .version("2.0")
                //描述
                .description("供测试使用")
                //
//                .termsOfServiceUrl("http://192.168.40.172:8080/swagger-ui.html")
                .build();
    }

    //配置静态资源
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

//    @Override
//    public void addResourceHandlers(ResourceHandlerRegistry registry) {
//        registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0);
//    }
}

注：若未配置静态资源，可能导致访问http://localhost:8080/fwmail/swagger-ui.html时提示访问404。

用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。@EnableSwagger2 表示开启Swagger

3、给Controller层添加注解

import com.jsyl.stfw.mail.fwmail.service.MailService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;

@RestController
@RequestMapping("/mail")
@Api("中文")
public class FwMailController {

    @Resource
    MailService mailService;

    @ApiOperation(value = "发送简易邮件",notes="note注意事项")
    @ApiImplicitParam(name = "to",value = "收件人",required = true,dataType = "String")
    @GetMapping("/send/{to}")
    public String sendmail(@PathVariable String to){
        mailService.sendmail(to);
        return "success///";
    }
}

4、访问路径http://localhost:8080/swagger-ui.html,发现Spring Boot中@Api( "用户")并没有生效，

需改为 @Api(tags = "中文",description = "描述")

5、访问接口时遇到一个问题，提示“Missing URI template variable 'to' for method parameter of type String”

原因是Controller中@PathVariable与@RequestMapping的变量名不一致

原来是
@ApiOperation(value = "发送简易邮件",notes="note注意事项")
    @ApiImplicitParam(name = "to",value = "收件人",required = true,dataType = "String")
    @GetMapping("/send")
    public String sendmail(@PathVariable String to){
        mailService.sendmail(to);
        return "success///";
    }


现在是
@ApiOperation(value = "发送简易邮件",notes="note注意事项")
    @ApiImplicitParam(name = "to",value = "收件人",required = true,dataType = "String")
    @GetMapping("/send/{to}")
    public String sendmail(@PathVariable String to){
        mailService.sendmail(to);
        return "success///";
    }

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

SpringBoot2整合Swagger2

猜你喜欢