swagger搭建（基於springBoot）詳解

  前后端分離后，api接口文檔的維護就成了一個讓人頭疼的問題，api接口更新慢，或因開發工作量大，沒時間整理文檔，導致前后端分離后前端同學和后端同 學都糾結於文檔的問題。而swagger的出現，不亞於一道曙光，功能強大，ui簡潔美觀，提供在線測試，不能說完美，但基本上解決了文檔的問題

       本此搭建是基於springBoot項目，希望對大家有幫助

 

官方網站為：http://swagger.io/

步驟1.maven

在maven的pom文件中引入相關的依賴

 

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

 

 步驟2.配置Swagger的配置文件

    import java.util.ArrayList;  
    import java.util.List;  
      
    import org.springframework.context.annotation.Bean;  
    import org.springframework.context.annotation.Configuration;  
      
    import springfox.documentation.builders.ParameterBuilder;  
    import springfox.documentation.builders.ApiInfoBuilder;  
    import springfox.documentation.builders.PathSelectors;  
    import springfox.documentation.builders.RequestHandlerSelectors;  
    import springfox.documentation.schema.ModelRef;  
    import springfox.documentation.service.ApiInfo;  
    import springfox.documentation.spi.DocumentationType;  
    import springfox.documentation.spring.web.plugins.Docket;  
    import springfox.documentation.swagger2.annotations.EnableSwagger2;  
    import springfox.documentation.service.Parameter;  
    @Configuration  
    @EnableSwagger2  
    public class Swagger2 {  
      
        @Bean  
        public Docket createRestApi() {  
            ParameterBuilder tokenPar = new ParameterBuilder();    
            List<Parameter> pars = new ArrayList<Parameter>();    
            tokenPar.name("token").description("令牌")  
            .modelRef(new ModelRef("string")).parameterType("query").required(false).build();    
            pars.add(tokenPar.build());    
            return new Docket(DocumentationType.SWAGGER_2)  
                    .apiInfo(apiInfo())  
                    .select()  
                    .apis(RequestHandlerSelectors.basePackage("com.sst"))  
                    .paths(PathSelectors.any())  
                    .build().globalOperationParameters(pars)  ;  
        }  
      
        @SuppressWarnings("deprecation")  
        private ApiInfo apiInfo() {  
            return new ApiInfoBuilder()  
                    .title("個人測試")  
                    .description("個人測試用api")  
                    .termsOfServiceUrl("http://blog.csdn.net/penyoudi1")  
                    .contact("測試")  
                    .version("1.0")  
                    .build();  
        }  
      
    }  

 

 步驟3.在Controller中引入注解

 

    import org.springframework.web.bind.annotation.RequestMapping;  
    import org.springframework.web.bind.annotation.RestController;  
      
    import io.swagger.annotations.Api;  
    import io.swagger.annotations.ApiImplicitParam;  
    import io.swagger.annotations.ApiImplicitParams;  
    import io.swagger.annotations.ApiOperation;  
      
    @RestController    
    @RequestMapping("test")   
    @Api(value="測試接口Controller")  
    public class TestController {  
      
        @ApiOperation(value="測試用接口", notes="測試用接口" ,httpMethod="POST")  
        @ApiImplicitParams({  
            @ApiImplicitParam(name="name", value="用戶姓名", dataType = "String", required=true, paramType="form"),  
            @ApiImplicitParam(name="id", value="id", dataType = "int", required=false, paramType="form")  
        })  
        @RequestMapping("word")    
        public String HelloWord(String name,Integer id) {    
            return "Hello Word";    
        }  
          
          
    }  

 

然后輸入地址  http://127.0.0.1:8080/SpringSwaggerTest/swagger-ui.html

可以查看到

可以查看到

     看到這個頁面，說明配置成功！！

以上就是swagger基於springBoot的配置方法，下面詳細說一下具體的參數

swagger配置文件說明

    ParameterBuilder tokenPar = new ParameterBuilder();    
            List<Parameter> pars = new ArrayList<Parameter>();    
            tokenPar.name("token").description("令牌")  
            .modelRef(new ModelRef("string")).parameterType("query").required(false).build();    
            pars.add(tokenPar.build());  

這段代碼是默認參數，添加上后，所有的接口都會有一個公共參數，不需要在每個接口單獨配置 [java]

    .apis(RequestHandlerSelectors.basePackage("com.sst"))  

    return new ApiInfoBuilder()  
            .title("個人測試")  
            .description("個人測試用api")  
            .termsOfServiceUrl("http://blog.csdn.net/penyoudi1")  
            .contact("測試")  
            .version("1.0")  
            .build();  

這個是一些頁面展示數據的配置，用於標題，分組說明等

controller注解說明

    @Api(value="測試接口Controller")  

這個注解用於整個類上，對整個類中的接口列表進行簡單說明

    @ApiOperation(value="測試用接口", notes="測試用接口" ,httpMethod="POST")  

 

    @ApiOperation(value="測試用接口", notes="測試用接口" ,httpMethod="POST")  

 

    @ApiImplicitParams({  
            @ApiImplicitParam(name="name", value="用戶姓名", dataType = "String", required=true, paramType="form"),  
            @ApiImplicitParam(name="id", value="id", dataType = "int", required=false, paramType="form")  
        })  

@ApiImplicitParams是傳入參數的集合，里面可以包含多個參數

@ApiImplicitParam(name="name", value="用戶姓名", dataType = "String", required=true, paramType="form"),

name是參數的名稱，value是參數的說明，dataType是參數的類型，前端不是限制，僅做說明使用，required true時是必傳參數，false是選填參數。paramType是提交方式=-= 好像都是寫的from

以上就是基本的使用的參數說明

問題

1.在開發中遇到過，使用swagger做excel導出中文亂碼的問題，尚未解決，如果你也遇到了，可以單獨訪問下接口，嘗試下是否是swagger本身的問題