Swagger 3.0使用介绍

一、概述

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。 国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3） 对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证API 文档的及时性将有很大的帮助。

二、SpringFox 3.0.0亮点：

• Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
• Spring Integration支持。
• SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
• 具有自动完成功能的文档化配置属性。
• 更好的规范兼容性与2.0。
• 支持OpenApi 3.0.3。
• 零依赖。几乎只需要spring-plugin，swagger-core(https://github.com/swagger-api/swagger-core) ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

三、从现有2.x版本迁移

Spring Boot应用程序

• 删除早期版本中包含的库。特别去除springfox-swager2和springfox-stwagger-ui内含物。
• 删除@EnableSwagger2注释
• 添加spring mvc
• Springfox3.x删除了对guava 和其他第三方库的依赖（还不是零dep！依赖于spring插件和用于注释和模型的开放api库），因此如果您使用guava 谓词/函数，则需要转换到java8函数接口
• 如果您正在使用WebMvc，但尚未使用@EnableWebMvc注释，请添加此注释。

spring mvc

• 删除早期版本中包含的库。特别去除springfox-swager2和springfox-stwagger-ui内含物。
• 对于OpenAPI添加@EnableOpenApi注释（对于swagger 2.0添加@EnableSwagger2）
• 对于OpenAPI，添加springfox-oas库依赖项（对于swagger 2.0，使用springfox-swaker2）
• Springfox3.x删除了对番石榴和其他第三方库的依赖（还不是零dep！依赖于spring插件和用于注释和模型的开放api库），因此如果您使用番石榴谓词/函数，则需要转换到java8函数接口

注意：

应用主类增加注解@EnableOpenApi，删除之前版本的SwaggerConfig.java。

启动项目，访问地址：http://localhost:8080/swagger-ui/index.html，(注意swagger2.x版本中访问的地址的为http://localhost:8080/swagger-ui.html)

四、开发示例

1.导入依赖

Maven项目中引入springfox-boot-starter依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.application.yml配置

spring:
  application:
    name: springfox-swagger
server:
  port: 8080
# ===== 自定义swagger配置 ===== #
swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: springfox swagger 3.0整合Demo
  try-host: http://localhost:${server.port}

3.配置示例

package springfoxdemo.boot.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.AuthorizationScopeBuilder;
import springfox.documentation.builders.ImplicitGrantBuilder;
import springfox.documentation.builders.OAuthBuilder;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.BasicAuth;
import springfox.documentation.service.Contact;
import springfox.documentation.service.GrantType;
import springfox.documentation.service.LoginEndpoint;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.SecurityConfiguration;
import springfox.documentation.swagger.web.SecurityConfigurationBuilder;
import springfox.documentation.swagger1.annotations.EnableSwagger;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.petstore.controller.PetController;
import springfox.petstore.controller.PetStoreResource;
import springfox.petstore.controller.UserController;
import springfoxdemo.boot.swagger.web.HomeController;

import javax.print.Doc;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.function.Predicate;

import static springfox.documentation.builders.PathSelectors.*;

@SpringBootApplication
@EnableSwagger2 //Enable swagger 2.0 spec
@EnableOpenApi //Enable open api 3.0.3 spec
public class Application {
  public static void main(String[] args) {
    ApplicationContext ctx = SpringApplication.run(Application.class, args);
  }

  @Bean
  public PetController petController() {
    return new PetController();
  }

  @Bean
  public PetStoreResource petStoreController() {
    return new PetStoreResource();
  }

  @Bean
  public UserController userController() {
    return new UserController();
  }

  @Bean
  public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("full-petstore-api")
        .apiInfo(apiInfo())
        .select()
        .paths(petstorePaths())
        .build()
        .securitySchemes(Collections.singletonList(oauth()))
        .securityContexts(Collections.singletonList(securityContext()));
  }

  @Bean
  public Docket categoryApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("category-api")
        .apiInfo(apiInfo())
        .select()
        .paths(categoryPaths())
        .build()
        .ignoredParameterTypes(ApiIgnore.class)
        .enableUrlTemplating(true);
  }

  @Bean
  public Docket multipartApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("multipart-api")
        .apiInfo(apiInfo())
        .select()
        .paths(multipartPaths())
        .build();
  }

  private Predicate<String> categoryPaths() {
    return regex(".*/category.*")
        .or(regex(".*/category")
            .or(regex(".*/categories")));
  }

  private Predicate<String> multipartPaths() {
    return regex(".*/upload.*");
  }

  @Bean
  public Docket userApi() {
    AuthorizationScope[] authScopes = new AuthorizationScope[1];
    authScopes[0] = new AuthorizationScopeBuilder()
        .scope("read")
        .description("read access")
        .build();
    SecurityReference securityReference = SecurityReference.builder()
        .reference("test")
        .scopes(authScopes)
        .build();

    List<SecurityContext> securityContexts =
        Collections.singletonList(
            SecurityContext.builder()
                .securityReferences(Collections.singletonList(securityReference))
                .build());
    return new Docket(DocumentationType.SWAGGER_2)
        .securitySchemes(Collections.singletonList(new BasicAuth("test")))
        .securityContexts(securityContexts)
        .groupName("user-api")
        .apiInfo(apiInfo())
        .select()
        .paths(input -> input.contains("user"))
        .build();
  }

  @Bean
  public Docket openApiPetStore() {
    return new Docket(DocumentationType.OAS_30)
        .groupName("open-api-pet-store")
        .select()
        .paths(petstorePaths())
        .build();
  }

  private Predicate<String> petstorePaths() {
    return regex(".*/api/pet.*")
        .or(regex(".*/api/user.*")
            .or(regex(".*/api/store.*")));
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("Springfox petstore API")
        .description("Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum " +
            "has been the industry's standard dummy text ever since the 1500s, when an unknown printer "
            + "took a " +
            "galley of type and scrambled it to make a type specimen book. It has survived not only five " +
            "centuries, but also the leap into electronic typesetting, remaining essentially unchanged. " +
            "It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum " +
            "passages, and more recently with desktop publishing software like Aldus PageMaker including " +
            "versions of Lorem Ipsum.")
        .termsOfServiceUrl("http://springfox.io")
        .contact(new Contact("springfox", "", ""))
        .license("Apache License Version 2.0")
        .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
        .version("2.0")
        .build();
  }

  @Bean
  SecurityContext securityContext() {
    AuthorizationScope readScope = new AuthorizationScope("read:pets", "read your pets");
    AuthorizationScope[] scopes = new AuthorizationScope[1];
    scopes[0] = readScope;
    SecurityReference securityReference = SecurityReference.builder()
        .reference("petstore_auth")
        .scopes(scopes)
        .build();

    return SecurityContext.builder()
        .securityReferences(Collections.singletonList(securityReference))
        .forPaths(ant(".*/api/pet.*"))
        .build();
  }

  @Bean
  SecurityScheme oauth() {
    return new OAuthBuilder()
        .name("petstore_auth")
        .grantTypes(grantTypes())
        .scopes(scopes())
        .build();
  }

  @Bean
  SecurityScheme apiKey() {
    return new ApiKey("api_key", "api_key", "header");
  }

  List<AuthorizationScope> scopes() {
    return Arrays.asList(
        new AuthorizationScope("write:pets", "modify pets in your account"),
        new AuthorizationScope("read:pets", "read your pets"));
  }

  List<GrantType> grantTypes() {
    GrantType grantType = new ImplicitGrantBuilder()
        .loginEndpoint(new LoginEndpoint("http://petstore.swagger.io/api/oauth/dialog"))
        .build();
    return Collections.singletonList(grantType);
  }

  @Bean
  public SecurityConfiguration securityInfo() {
    return SecurityConfigurationBuilder.builder()
        .clientId("abc")
        .clientSecret("123")
        .realm("pets")
        .appName("petstore")
        .scopeSeparator(",")
        .build();
  }
}

五、一些常用注解说明

@Api：用在controller类，描述API接口

@ApiOperation：描述接口方法

@ApiModel：描述对象

@ApiModelProperty：描述对象属性

@ApiImplicitParams：描述接口参数

@ApiResponses：描述接口响应

@ApiIgnore：忽略接口方法