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：多個請求參數