SpringBoot 集成 Swagger的案例

小編給大家分享一下SpringBoot 集成 Swagger的案例，相信大部分人都還不怎么了解，因此分享這篇文章給大家參考一下，希望大家閱讀完這篇文章后大有收獲，下面讓我們一起去了解一下吧！

什么是Swagger

1. Swagger 可以生成一個具有互動性的API控制臺，開發者可以用來快速學習和嘗試API
2. Swagger 可以生成客戶端SDK代碼用于各種不同的平臺上的實現
3. Swagger 文件可以在許多不同的平臺上從代碼注釋中自動生成
4. Swagger 有一個強大的社區

依賴導入

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

加入配置

swagger:
  title: 項目 API
  description: SpringBoot 集成 Swagger 項目 API
  version: 1.0
  terms-of-service-url: http://www.baidu.com/
  base-package: cn.anothertale.springbootshiro  # 這一項指定需要生成 API 的包，一般就是 Controller
  contact:
    name: taohan
    url: http://www.baidu.ccom/
    email: 1289747698@qq.com

建立 Swagger Config

package cn.anothertale.springbootshiro.config.swagger;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.context.properties.ConfigurationProperties;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * description: swagger 配置中心
 *
 * @author: taohan
 * @date: 2019年03月20日
 * @time: 16:52
 */
@Getter
@Setter
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

    /**
     * API 接口包路徑
     */
    private String basePackage;

    /**
     * API 頁面標題
     */
    private String title;

    /**
     * API 描述
     */
    private String description;

    /**
     * 服務條款地址
     */
    private String termsOfServiceUrl;

    /**
     * 版本號
     */
    private String version;

    /**
     * 聯系人
     */
    private Contact contact;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .version(version)
                .contact(contact)
                .build();
    }
}

通過注解標明 API

Swagger 默認根據配置的包，掃描所有接口并生成對應的 API 描述和參數信息。

常用注解及對應屬性如下：

• @Api (描述一個 API 類，標注在 Controller 上)

  1. value：url 的路徑值
  2. tags：如果設置該值，value 的值會被覆蓋
  3. description：API 的資源描述
  4. basePath：基本路徑可以不設置
  5. produces：比如：application/json, application/xml 類似 RequestMapping 對應屬性
  6. consumes：比如：application/json, application/xml
  7. authorizations：高級特性認證時配置
  8. hidden：是否在文檔中隱藏
     
     

• @ApiOperation (用在 Controller 方法上，說明方法的作用)

  1. value：url 的路徑值
  2. tags：如果設置該值，value 的值會被覆蓋
  3. description：對 API 資源的描述
  4. basePath：基本路徑可以不設置
  5. position：如果配置多個 API 想改變展示位置，可通過該屬性設置
  6. response：返回的對象
  7. responseContainer：這些對象是有效的 List、Set、Map，其他無效
  8. httpMethod：請求方式
  9. code：HTTP 狀態碼，默認200
  10. extensions：擴展屬性
      
      

• @ApiImplicitParams (用在 Controller 方法上，描述一組請求參數)

  1. value：ApiImplicitParam 數組，見下一注解
     
     

• @ApiImplicitParam(描述一個請求參數)

  1. name：參數名稱
  2. value：參數值
  3. defaultValue：參數默認值
  4. required：是否必須，默認 false
  5. access：不過多描述
  6. example：示例
     
     

• @ApiResponses (描述一組響應)

  1. value：ApiResponse數組，見下一注解
     
     

• @ApiResponse (描述一個響應)

  1. code：HTTP 的狀態碼
  2. message：描述消息

最后，可以在瀏覽器中輸入 http://localhost:8080/swagger-ui.html 即可訪問！

以上是SpringBoot 集成 Swagger的案例的所有內容，感謝各位的閱讀！相信大家都有了一定的了解，希望分享的內容對大家有所幫助，如果還想學習更多知識，歡迎關注億速云行業資訊頻道！