SpringBoot入門建站全系列（十六）整合Swagger文檔中心

時間：2023-07-28 19:48:01 | 來源：網(wǎng)站運營

時間：2023-07-28 19:48:01 來源：網(wǎng)站運營

SpringBoot入門建站全系列（十六）整合Swagger文檔中心：

SpringBoot入門建站全系列（十六）整合Swagger文檔中心

一、概述

Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)?？傮w目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新 。接口的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

swagger可以與Spring MVC程序配合組織出強大RESTful API文檔。它既可以減少我們創(chuàng)建文檔的工作量，同時說明內(nèi)容又整合入實現(xiàn)代碼中，讓維護文檔和修改代碼整合為一體，可以讓我們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能 來調(diào)試每個RESTful API。

代碼可以在Spring組件化構(gòu)建https://www.pomit.cn/java/spring/springboot.html中的Swagger組件中查看，并下載。

首發(fā)地址： 品茗IT-同步發(fā)布

品茗IT 提供在線支持：

一鍵快速構(gòu)建Spring項目工具

一鍵快速構(gòu)建SpringBoot項目工具

一鍵快速構(gòu)建SpringCloud項目工具

一站式Springboot項目生成

Mysql一鍵生成Mybatis注解Mapper

如果大家正在尋找一個java的學(xué)習(xí)環(huán)境，或者在開發(fā)中遇到困難，可以加入我們的java學(xué)習(xí)圈，點擊即可加入，共同學(xué)習(xí)，節(jié)約學(xué)習(xí)時間，減少很多在學(xué)習(xí)中遇到的難題。

二、配置

本文假設(shè)你已經(jīng)引入spring-boot-starter-web。已經(jīng)是個SpringBoot項目了,如果不會搭建，可以打開這篇文章看一看《SpringBoot入門建站全系列（一）項目建立》。

2.1 Maven依賴

使用swagger需要引入springfox-swagger2，如果要使用swagger的界面，需要引入springfox-swagger-ui。

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version></dependency>

2.2 配置文件

基于注解配置Swagger，暫不需要額外配置參數(shù)。

三、Swagger配置

3.1 開啟Swagger

SwaggerConfig:

package com.cff.springbootwork.swagger.config;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.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.cff.springbootwork")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文檔") .description("簡單優(yōu)雅的restful風(fēng)格") .version("1.0") .build(); }}這里，@EnableSwagger2開啟Swagger。@Configuration注解聲明這里可以配置bean。

3.2 手動增加Swagger接口說明（可有可無）

有時候，Swagger是獲取不到一些接口的信息，這樣在界面上就無法顯示出這些接口信息。如由SpringSecurity控制的登入等登出接口，這時候我們可以手動添加這些接口：

SwaggerAddtionScanConfig：

package com.cff.springbootwork.swagger.config;import java.util.ArrayList;import java.util.Arrays;import java.util.Collections;import java.util.List;import java.util.Set;import org.springframework.http.HttpMethod;import org.springframework.stereotype.Component;import com.cff.springbootwork.swagger.entity.TestEntity;import com.fasterxml.classmate.TypeResolver;import springfox.documentation.builders.OperationBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.ResponseMessageBuilder;import springfox.documentation.schema.ModelRef;import springfox.documentation.service.ApiDescription;import springfox.documentation.service.ResponseMessage;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spi.service.ApiListingScannerPlugin;import springfox.documentation.spi.service.contexts.DocumentationContext;import springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator;/** * 該文件可有可無，手動增加接口的方法 * @author fufei * */@Componentpublic class SwaggerAddtionScanConfig implements ApiListingScannerPlugin { @Override public List<ApiDescription> apply(DocumentationContext documentationContext) { return new ArrayList<>( Arrays.asList( new ApiDescription("Login", "/login", "登錄接口", Collections .singletonList( new OperationBuilder(new CachingOperationNameGenerator()).authorizations(new ArrayList<>()) .method(HttpMethod.POST) .summary("登錄接口") .notes("登錄接口")//方法描述 .tags(Collections.singleton("登錄登出模塊"))//歸類標(biāo)簽 .produces(Collections.singleton("application/json")) .consumes(Collections.singleton("application/json")) .parameters( Arrays.asList( new ParameterBuilder() .description("email") .type(new TypeResolver() .resolve(String.class)) .name("email") .parameterType("query") .parameterAccess("access") .required(true) .modelRef(new ModelRef("string")) .build(), new ParameterBuilder() .description("password") .type(new TypeResolver() .resolve(String.class)) .name("password") .parameterType("query") .parameterAccess("access") .required(true) .modelRef(new ModelRef("string")) .build() )) .responseMessages(responseMessages()) .build()), false), new ApiDescription("Login", "/logout", "登出接口", Collections .singletonList( new OperationBuilder(new CachingOperationNameGenerator()).authorizations(new ArrayList<>()) .method(HttpMethod.POST) .summary("登出接口") .notes("登出接口")//方法描述 .tags(Collections.singleton("登錄登出模塊"))//歸類標(biāo)簽 .produces(Collections.singleton("application/json")) .parameters( Collections .singletonList(new ParameterBuilder() .description("token") .type(new TypeResolver() .resolve(String.class)) .name("token") .parameterType("query") .parameterAccess("access") .required(true) .modelRef(new ModelRef("string")) .build())) .responseMessages(responseMessages()) .build()), false))); } /** * @return Set of response messages that overide the default/global response * messages */ private Set<ResponseMessage> responseMessages() { // <8> return Collections.singleton( new ResponseMessageBuilder().code(200).message("Successfully received bug 1767 or 2219 response") .responseModel(new ModelRef( TestEntity.class.getSimpleName()) ).build()); } @Override public boolean supports(DocumentationType documentationType) { return DocumentationType.SWAGGER_2.equals(documentationType); }}

四、測試Swagger

我們使用一些Swagger的注解來做測試，如果不加注解其實也是可以的，但是不方便觀看，加注解的話可以顯示寫的內(nèi)容。

SwaggerRest ：

package com.cff.springbootwork.swagger.web;import java.util.UUID;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RequestParam;import org.springframework.web.bind.annotation.RestController;import com.cff.springbootwork.swagger.entity.TestEntity;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;@Api(tags = {"測試模塊"}, produces = "application/json")@RestController@RequestMapping("/swagger")public class SwaggerRest { @ApiOperation(value = "測試swagger的功能") @RequestMapping(value = "/test", method = { RequestMethod.GET }) public TestEntity test(@RequestParam String reqType) { String uuid = UUID.randomUUID().toString(); String welMsg = "welcome 程序猿"; if (reqType != null && "1000".equals(reqType)) { welMsg = "welcome 程序媛"; } TestEntity welEntity = new TestEntity(); welEntity.setUuid(uuid); welEntity.setWelMsg(welMsg); return welEntity; } @RequestMapping(value = "/test2", method = { RequestMethod.GET }) public TestEntity test2(@RequestParam String reqType) { String uuid = UUID.randomUUID().toString(); String welMsg = "welcome 程序猿"; if (reqType != null && "1000".equals(reqType)) { welMsg = "welcome 程序媛"; } TestEntity welEntity = new TestEntity(); welEntity.setUuid(uuid); welEntity.setWelMsg(welMsg); return welEntity; }}

五、過程中用到的實體

TestEntity：

package com.cff.springbootwork.swagger.entity;public class TestEntity { private String uuid; private String welMsg; public String getUuid() { return uuid; } public void setUuid(String uuid) { this.uuid = uuid; } public String getWelMsg() { return welMsg; } public void setWelMsg(String welMsg) { this.welMsg = welMsg; }}

快速構(gòu)建項目

Spring組件化構(gòu)建

SpringBoot組件化構(gòu)建

SpringCloud服務(wù)化構(gòu)建

喜歡這篇文章么，喜歡就加入我們一起討論SpringBoot使用吧！