Spring Boot之Swagger 3.0

為了提高前后端開發人員之間的溝通效率，so, 它出世了。

---

添加Swagger 3.0的依賴

添加依賴在

dependencies {
    // add Swagger3
    compile group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
    }
}

創建Swagger 3.0的配置類SwaggerConfiguration.java

---

ps: 此文件必須與xxxxApplication.java入口類在同級包下

import io.swagger.models.auth.In;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.*;

@Configuration
@EnableOpenApi
public class SwaggerConfiguration implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.icodesoft.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .protocols(new LinkedHashSet<>(Arrays.asList("HTTPS", "HTTP")))
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private List<SecurityScheme> securitySchemes() {
        ArrayList<SecurityScheme> auth = new ArrayList<>();
        auth.add(basicAuthScheme());
        auth.add(apiKeyScheme());
        return auth;
    }

    private SecurityScheme basicAuthScheme() {
        return HttpAuthenticationScheme.BASIC_AUTH_BUILDER.name("dc_auth").build();
    }

    private SecurityScheme apiKeyScheme() {
        return new ApiKey("dc_token", "Authorization", In.HEADER.toValue());
    }

    private List<SecurityContext> securityContexts() {
        SecurityContext securityContext = SecurityContext.builder()
                .securityReferences(Arrays.asList(basicAuthReference(), apiKeyReference()))
                .build();
        return Collections.singletonList(securityContext);
    }

    private SecurityReference basicAuthReference() {
        return new SecurityReference("dc_auth", new AuthorizationScope[0]);
    }

    private SecurityReference apiKeyReference() {
        return new SecurityReference("dc_token", new AuthorizationScope[]{new AuthorizationScope("global", "")});
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Api Documentation")
                .description("XXX service apis")
                .contact(new Contact("Gary", null, "email"))
                .version("1.0")
                .build();
    }
}

新建controller包，並在其下新建HomeController類

---

package com.icodesoft.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(tags = "主頁接口")
@RequestMapping("/home")
public class HomeController {

    @ApiOperation(value="獲取用戶詳細信息", notes="")
    @GetMapping("index")
    public String index() {
        return "This is my first page!";
    }

    @ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")
    @ApiImplicitParam(name = "id", value = "用戶ID", defaultValue="100", required = true)
    @GetMapping(value="/username")
    public String getUserName(@RequestParam(required = true) Long id) {
        return "gary";
    }

    @ApiOperation(value="獲取用戶郵箱", notes="根據url的id來獲取用戶郵箱")
    @ApiImplicitParam(name = "id", value = "用戶ID", defaultValue="gary", required = true)
    @RequestMapping(value="/email/{userName}", method= RequestMethod.GET)
    public String getEmailAddress(@PathVariable String userName) {
        return userName + " ==================: [e-mail]";
    }
}

運行測試

---