Spring Boot Swagger 3

Spring Boot Swagger 3 – Spring Boot 168 EP 10

Post author:若雪
Post published:2021-03-02
Post category:RD / Spring Boot
Post comments:0 Comments
Post last modified:2023-02-18

對於 RESTful API 來說重要的一部分內容就是文件，Swagger 3 提供了一套通過程式碼和註解自動生成文件的方法，對於保證 API 文件的即時性有很大的幫助， EP 10 增加了相依套件及設定產出 API 文件。

Table of Contents

功能簡介

Swagger 是一套基於 OpenAPI 規範的開源工具，可以幫助設計、建構、記錄以及使用 Rest API。

檔案目錄

./
   +- build.gradle
       +- src
           +- main
               +- resources
               |   +- application.properties
               +- java
               |   +- org
               |       +- ruoxue
               |           +- spring_boot_168
               |               +- config
               |                   +- Swagger3Config.java

Gradle

build.gradle

增加 Springfox Boot Starter 。

修改完後，點右鍵，Gradle -> Refresh Gradle Project 。

buildscript {
	group 'org.ruoxue.spring-boot-168'
	version = '0.0.1-SNAPSHOT'
	ext {
		swaggerVersion = '3.0.0'
	}
}

dependencies {
	implementation "io.springfox:springfox-boot-starter:${swaggerVersion}"
}

組態設定

application.properties

Swagger Spring Boot 增加 Springfox 設定。

springfox.documentation.enabled=true

產品環境時，應把 springfox.documentation.enabled 設為 false。

Swagger3Config.java

Spring Swagger 新增檔案，增加設定。

package org.ruoxue.spring_boot_168.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@EnableOpenApi
@EnableKnife4j
@Configuration
@ConditionalOnProperty(name = "springfox.documentation.enabled", havingValue = "true")
public class Swagger3Config {
	
	public Swagger3Config() {
		
	}
	
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.ruoxue.spring_boot_168"))
                .paths(PathSelectors.any())
                .build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SB 168")
                .description("SB 168")
                .contact(new Contact("若雪", "https://www.ruoxue.org", "ruoxueorg@gmail.com"))
                .version("0.0.1")
                .build();
    }
}