簡介

swagger 提供最強大，最易用的工具，以充分利用OpenAPI規範。

官網 ： https://swagger.io/

準備工作

• pom.xml jar引入： <swagger.version>2.9.2</swagger.version>

     <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
 

目的

之前使用swagger都是直接在類，方法，實體上寫api引入的參數，這給人一種代碼很不清爽的感覺，所以采用yaml文件編輯的模式，是代碼看著更簡單。

項目結構

• 1.創建SwaggerConfig類

package com.honghh.bootfirst.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

/**
 * ClassName: SwaggerConfig
 * Description:
 *
 * @author honghh
 * @date 2019/02/20 14:28
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation註解的類，生成接口文檔
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的類，生成接口文檔
                //.apis(RequestHandlerSelectors.basePackage("com.honghh.bootfirst.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("boot-demo")
                .description("boot-demo文檔")
                .termsOfServiceUrl("http://www.boot-demo.cn")
                .version("1.0.0")
                .build();
    }

}
 

• 2.引入swagger展示層代碼，代碼我將上傳到碼雲 https://gitee.com/honghh/boot-demo.git
• 3.配置yaml文件

#必要字段！Swagger規範版本，必須填2.0，否則該YAML將不能用於Swagger其他組件
swagger: ‘2.0‘
#必要字段！描述API接口信息的元數據
info:
  #接口文檔的描述
  description: swagger說明文檔，讓一切都變得如此簡單。
  #版本號
  version: 1.0.0
  #接口標題
  title: boot-demo
#Swagger會提供測試用例，host指定測試時的主機名，如果沒有指定就是當前主機,可以指定端口．
host: localhost:8080
#定義的api的前綴，必須已/開頭,測試用例的主機則為:host＋bashPath
#basePath: /boot-demo

#指定調用接口的協議，必須是:"http", "https", "ws", "wss"．默認是http.-表示是個數組元素，即schemes接受一個數組參數
schemes:
  - http
  - https

#對應與http協議頭request的Accept，調用者可接受類型,默認是*/*,定義的類型必須是http協議定義的 Mime Types,RestfulAPI一般定義成application/json
#這兩個是對所有接口的全局設置，在細化的接口中是還可以對應這兩個屬性來覆蓋全局屬性
produces:
  - application/json

#定義接口數據
paths:
  /myInfo:
    #必要字段!定義HTTP操作方法，必須是http協議定義的方法
    get:
      tags:
        - MyInfo 用戶信息
      #接口概要
      summary: 用戶信息
      #接口描述
      description: 查詢出所有用戶的所有信息，用戶名，別名
      parameters:
        - name: id
          description: 用戶ID
          in: query
          type: integer
          required: true
      #返回值描述，必要自動
      responses:
        #返回的http狀態碼
        200:
          description: 所有用戶信息或者用戶的集合信息
          #描述返回值
          schema:
            #返回值格式，可選的有array,integer,string,boolean
            $ref: ‘#/definitions/myInfo‘

#定義數據模型
definitions:
  R:
    type: object
    properties:
      code:
        description: 狀態碼 0：成功  非0：失敗
        type: integer
        format: int32
      msg:
        description: 失敗原因
        type: string
  myInfo:
    type: object
    properties:
      id:
        description: ID
        type: integer
        format: int32
      age:
        description: 年齡
        type: integer
      name:
        description: 姓名
        type: string
 

4.啟動項目，輸入：http://localhost:8080/swagger/index.html 運行如圖


有關yaml編寫的規範以及字段的意義，這裏我就不一一說明，參考上面yaml文件中的註釋，或參考下面文章，再不然就自行百度

參考文獻

• Swagger編寫API文檔的YAML中文示例 https://blog.csdn.net/u010466329/article/details/78522992

• YAML、YML在線編輯器(格式化校驗)
  http://www.bejson.com/validators/yaml_editor/

文章來源： https://blog.csdn.net/qq_35098526/article/details/87802697

六、springboot整合swagger