SpringBoot+Swagger配置及注解詳解


swagger配置及注解詳解

   1.加入依賴的jar包

  

<!--引入swagger的依賴-->
     <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.9.2</version>
     </dependency>

2.配置swagger配置文件

 

package com.jt.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.google.common.base.Predicates;

import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * Swagger2的接口配置
 * 在與spring boot集成時,放在與Application.java同級的目錄下。
 * 通過@Configuration注解,讓Spring來加載該類配置。
 * 再通過@EnableSwagger2注解來啟用Swagger2。
 * @author DragonBai
 *
 */
@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable}") //開啟訪問接口文檔的權限
public class SwaggerConfig {
    /**
     * 創建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket( DocumentationType.SWAGGER_2 )
                // 用來創建該API的基本信息,展示在文檔的頁面中(自定義展示的信息)
                .apiInfo( apiInfo() )
                // 設置哪些接口暴露給Swagger展示
                .select()
                // (第一種方式)掃描所有有注解的api,用這種方式更靈活
                .apis( RequestHandlerSelectors.withMethodAnnotation( ApiOperation.class ) )
                // (第二種方式)掃描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.hubiao.pay.merchant.controller"))
                // (第三種方式)掃描所有 
                //.apis(RequestHandlerSelectors.any())
                .paths( PathSelectors.any() )
                //(第四種方式)只顯示api路徑下的頁面
                //.paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }

    /**
     * 添加摘要信息
     * 創建該API的基本信息(這些基本信息會展現在文檔頁面中)
     * 訪問地址:http://項目實際地址/swagger-ui.html
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder進行定制
        return new ApiInfoBuilder()
                // 設置標題
                .title( "標題:商戶應用API文檔" )
                // 描述
                .description( "描述:向前端提供商戶應用的ResultFul風格接口文檔" )
                // 作者信息
                //.contact( "hubiao" )
                .contact(new Contact("DragonBai", "http://www.DragonBai.cn", "z591593455@qq.com"))
                // 版本
                .version( "版本號:" + "V1.0.0" )
                .build();
    }
}

3.生成swagger文檔

package com.jt.controller;


import org.springframework.beans.factory.annotation.Autowired;
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.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.jt.pojo.Users;
import com.jt.server.UserService;
import com.jt.util.JsonResult;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
/**
 * Swagger使用的注解及其說明:

@Api:用在類上,說明該類的作用。

@ApiOperation:注解來給API增加方法說明。

@ApiParam:用對象來接收參數
   public ResponseEntity<Merchant> merchantAdd(@RequestBody @ApiParam(name="第一個參數", value = "Merchant", required = true)  Merchant merchant)
@ApiImplicitParams : 用在方法上包含一組參數說明。 @ApiImplicitParam:用來注解來給方法入參增加說明。 @ApiResponses:用於表示一組響應 @ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息 l code:數字,例如400 2 message:信息,例如"請求參數沒填好" 3 response:拋出異常的類 例:方法返回void時 @ApiResponses(value = { @ApiResponse(code = 1, message = "當http狀態碼為200,且返回code=ok時,data集合中的對象結構", response = PersonResponse.class) }) @ApiModel:描述一個Model的信息(一般用在請求參數無法使用@ApiImplicitParam注解進行描述的時候) l @ApiModelProperty:描述一個model的屬性 例:接收對象傳參的例子在POJO上增加 //@ApiModel(value="醫生對象模型") //public class DemoDoctor{ // @ApiModelProperty(value="id" ,required=true) // private Integer id; // @ApiModelProperty(value="醫生姓名" ,required=true) // private String name;} 在后台采用對象接收參數時,Swagger自帶的工具采用的是JSON傳參, 測試時需要在參數上加入@RequestBody *
@author DragonBai * */ @Slf4j @RestController //用在類上,說明該類的作用。 @RequestMapping("/api") @Api(value = "商戶平台應用接口",tags = "用戶操作接口") public class UserSWController {//http://localhost:8090/swagger-ui.html#/ @Autowired private UserService userService; /** * @ApiImplicitParam的參數說明: * paramType:指定參數放在哪個地方: *1.header:請求參數放置於Request Header,使用@RequestHeader獲取 2.query:請求參數放置於請求地址,使用@RequestParam獲取 3.path:(用於restful接口)-->請求參數的獲取:@PathVariable 4.body:請求參數放置body @RequestBody 5.form:請求參數放置form表單序列化(不常用) *name:參數名 *dataType:參數類型 int string long 小寫 *required:參數是否必須傳 true | false *value:說明參數的意思 *defaultValue:參數的默認值 * * @param userId * @return */ @ApiOperation(value="根據用戶編號獲取用戶信息",httpMethod = "GET", notes="test: 僅1和2有正確返回") @ApiImplicitParam(paramType="path", name = "userId", value = "用戶ID", required = true, dataType = "int",example = "7") //@GetMapping("/{userId}")//不能使用否則,訪問不了頁面 @RequestMapping(value = "/{userId}",method =RequestMethod.GET) public JsonResult<Users> getUser(@PathVariable Integer userId) { log.info("get user, userId="+userId); Users u = userService.getUser(userId); return JsonResult.ok(u); } @ApiOperation(value = "添加用戶積分",httpMethod = "GET") @ApiImplicitParams({ @ApiImplicitParam(paramType="path", name = "userId", value = "用戶ID", required = true, dataType = "int",example = "7"), @ApiImplicitParam(paramType="query", name = "score", value = "用戶積分", required = true, dataType = "int",example = "100") }) //@GetMapping("/{userId}/score") @RequestMapping(value = "/{userId}/score",method =RequestMethod.GET) public JsonResult addScore(@PathVariable Integer userId, Integer score) { userService.addScore(userId, score); return JsonResult.ok(); } }

問題:找不到html頁面可能是參數類型對應swagger錯誤,也可能是靜態資源加載過濾

        paramType會直接影響程序的運行期,如果paramType與方法參數獲取使用的注解不一致,會直接影響到參數的接收

       dataType類型要對應正確,否則swagger測試無法輸入參數報紅框,后台沒有反應

       Conntroller中定義的方法必須在@RequestMapper中顯示的指定RequestMethod類型,否則SawggerUi會默認為全類型皆可訪問, API列表中會生成多條項目

        1.//@GetMapping("/{userId}")//不能使用否則,訪問不了頁面,@GetMapping("/{id}"), 正好與測試頁面的網址相互沖突,去掉“/”

        2.過濾設置,不搬沒錯不用

       3.在使用@ApiModelProperty注解在字段上時,如果字段的類型為Long或是int類型,那么程序啟動后,訪問swagger-ui.html的頁面,程序會報錯
           #java.lang.NumberFormatException: For input string: ""

       解決:yml

#添加日志輸出
logging:
  level:
    com.jt.mapper: debug
    io.swagger.models.parameters.AbstractSerializableParameter: error

 

    或者@ApiImplicitParam加上example

 

    @ApiImplicitParam(paramType="path", name = "userid", value = "用戶ID", required = true, dataType = "int",example = "7")

 

     

//package com.jt.config;
//
//import org.springframework.context.annotation.Configuration;
//import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
//import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
//
//@Configuration
//public class WebMvcConfig extends WebMvcConfigurerAdapter {
//    @Override
//    public void addResourceHandlers(ResourceHandlerRegistry registry) {
//        //在配置靜態資源時捕獲swagger-ui.html映射到"classpath:/META-INF/resources/"
////        registry.addResourceHandler("swagger-ui.html")
////                .addResourceLocations("classpath:/META-INF/resources/");
//        
//        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
//        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
//        
//        registry.addResourceHandler("/templates/**")
//                .addResourceLocations("classpath:/META-INF/resources/templates/");
//    }
//}
//

 

 

 

參考:https://blog.csdn.net/qq_39082353/article/details/109453310?utm_term=swagger%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E8%AF%A6%E8%A7%A3

 

   https://blog.csdn.net/sanyaoxu_2/article/details/80555328

  https://blog.csdn.net/wyb880501/article/details/79576784

 


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM