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:忽略接口方法

相关推荐
仰望星空@脚踏实地11 分钟前
Spring Boot Web 服务单元测试设计指南
spring boot·后端·单元测试
一勺菠萝丶2 小时前
Spring Boot + MyBatis/MyBatis Plus:XML中循环处理List参数的终极指南
xml·spring boot·mybatis
RainbowSea3 小时前
问题:后端由于字符内容过长,前端展示精度丢失修复
java·spring boot·后端
风象南3 小时前
SpringBoot 控制器的动态注册与卸载
java·spring boot·后端
我是一只代码狗4 小时前
springboot中使用线程池
java·spring boot·后端
hello早上好4 小时前
JDK 代理原理
java·spring boot·spring
PanZonghui4 小时前
Centos项目部署之运行SpringBoot打包后的jar文件
linux·spring boot
沉着的码农5 小时前
【设计模式】基于责任链模式的参数校验
java·spring boot·分布式
zyxzyx6665 小时前
Flyway 介绍以及与 Spring Boot 集成指南
spring boot·笔记
一头生产的驴6 小时前
java整合itext pdf实现自定义PDF文件格式导出
java·spring boot·pdf·itextpdf