SpringBoot整合Swagger學習

什麼是Swagger？

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務.總體目標是使客戶端和文件系統作爲服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。

官網：https://swagger.io/

主要作用

• 接口的文檔在線自動生成
• 功能測試

手寫Api文檔的幾個痛點：

1. 文檔需要更新的時候，需要再次發送一份給前端，也就是文檔更新交流不及時。
2. 接口返回結果不明確
3. 不能直接在線測試接口，通常需要使用工具，比如postman
4. 接口文檔太多，不好管理

Swagger也就是爲了解決這個問題，當然也不能說Swagger就一定是完美的，當然也有缺點，最明顯的就是代碼移入性比較強。

其他的不多說，想要了解Swagger的，可以去Swagger官網，可以直接使用Swagger editor編寫接口文檔，當然我們這裏講解的是SpringBoot整合Swagger2，直接生成接口文檔的方式。

Swagger的開源項目

• Swagger-tools：提供各種與Swagger進行集成和交互的工具
• Swagger-core：用於Java/Scala的的Swagger實現
• Swagger-js: 用於JavaScript的Swagger實現
• Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架
• Swagger Editor：基於瀏覽器的編輯器，您可以在其中編寫OpenAPI規範
• Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以爲Swagger兼容API動態生成優雅文檔
• Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼

SpringBoot+Swagger

不會springBoot請看：

• 添加swagger依賴

• <dependency>
      <groupId>com.spring4all</groupId>
      <artifactId>swagger-spring-boot-starter</artifactId>
      <version>1.7.1.RELEASE</version>
  </dependency>

   

• 配置swagger
• 配置文件配置：

  #swagger頁面標題
  swagger.title=spring-boot-&-Swagger2
  #swagger頁面鏈接模塊標題
  swagger.description=Link info
  #swagger標題上的版本號
  swagger.version=1.0
  #鏈接信息：顯示名稱
  swagger.contact.name=login application
  #鏈接信息：鏈接地址
  swagger.contact.url=http://localhost:8080/login
  #掃描包路徑下的API註解生成API信息（自己創建的controller包路徑）
  swagger.base-package=com.springboot.web.controller

  使用配置類：

  @Configuration
    @EnableSwagger2Doc
    public class AddResource {
      @Bean
      public Docket createRestApi() {
          // 創建API頁面展示信息
          ApiInfo apiInfo = new ApiInfoBuilder()
          // 頁面標題 swagger-ui.html的標題
          .title("SpringBoot整合Swagger2")
          // 描述下的鏈接信息
          .contact(new Contact("Loyal", "http://localhost:8080/login", ""))
          // 版本號  頁面標題上顯示的版本號
          .version("1.0")
          // 頁面API文檔的描述信息
          .description("API 描述").build();
  
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo)
                  .select()
                  .apis(
                          // 將包路徑下所有方法掃描成API
                          RequestHandlerSelectors.basePackage("com.springboot.web.controller")
                        )
                  .paths(PathSelectors.any())
                  .build();
      }
  
    }

• 註解配置API文檔內容

  @Api("Swagger 耍耍水")
    @RestController
    public class LoginController {
  
      Logger logger = LoggerFactory.getLogger(LoginController.class);
  
      @Autowired
        private MessageSource messageSource;
      // 定義API描述信息
      @ApiOperation(value="登錄",notes="用戶登錄系統")
        // 定義API參數
      @ApiImplicitParams({
          @ApiImplicitParam(name="name",paramType="query",dataType="String",value="用戶名",required=true),
          @ApiImplicitParam(name="pwd",paramType="query",dataType="String",value="密碼",required=true)
      })
        @ApiResponses({
          @ApiResponse(code=200,message="請求成功了哦！"),
          @ApiResponse(code=404,message="頁面去哪了？")
      })
      @RequestMapping("/login")
      public Map<String,Object> login(String name,String pwd) {
          logger.info("LoginController.login()===");
          Map<String,Object> model = new HashMap<String,Object>();
          model.put("resultCode", "success");
          model.put("resultMsg", "Operation success!");
          return model;
      }
  
        @ApiOperation(value="Test測試",notes="API測試耍耍！")
      @RequestMapping(value="/test",method=RequestMethod.POST)
      @ApiParam(name="用戶對象",value="傳入json格式",required=true)
      public String test(@RequestBody User user) {
          System.out.println("UserController.test()");
          return "success";
      }
    }

   

• 實體類註解

  @ApiModel(value = "User", description = "用戶信息描述")
    public class User {
        /**
         * 學號
         */
        @ApiModelProperty("證件號")
        private int    id;
        /**
         * 姓名
         */
        @ApiModelProperty("姓名")
        private String name;
        /**
         * 年齡
         */
        @ApiModelProperty("年齡")
        private int    age;
        /**
         * 性別
         */
        @ApiModelProperty("性別")
        private String sex;
        /**
         * 住址
         */
        @ApiModelProperty("家庭住址")
        private String address;
    }

  訪問路徑：http://localhost:8080/swagger-ui.html

 

相關注解：

• @Api：標註類中所有方法爲API
• @ApiOperation：API方法定義
• @ApiImplicitParams：API參數集合
• @ApiImplicitParam：API參數定義
• paramType屬性：
  • header：請求參數放置於Request Header，使用@RequestHeader獲取
  • query：請求參數放置於請求地址，使用@RequestParam獲取
  • path：（用於restful接口）-->請求參數的獲取：@PathVariable
  • body
• @ApiResponses：API響應集合
• @ApiResponse：API響應定義
• @ApiIgnore：忽略該API
• @ApiError ：發生錯誤返回的信息