溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務條款》
您好，登錄后才能下訂單哦！
怎么在SpringBoot中利用Swagger構建一個api文檔？相信很多沒有經驗的人對此束手無策，為此本文總結了問題出現的原因和解決方法，通過這篇文章希望你能解決這個問題。
Swagger是什么：THE WORLD'S MOST POPULAR API TOOLING
根據官網的介紹：
Swagger Inspector：測試API和生成OpenAPI的開發工具。Swagger Inspector的建立是為了解決開發者的三個主要目標。
1、執行簡單的API測試
2、生成OpenAPI文檔
3、探索新的API功能
我的理解Swagger是一個規范和完整的框架，用于生成、描述、調用和可視化RESTful風格的Web服務。簡單來說，Swagger是一個功能強大的接口管理工具，并且提供了多種編程語言的前后端分離解決方案。根據我的使用，當然我只是最簡單的使用，我感覺Swagger有以下幾個優點：
1、Swagger可以整合到代碼中，在開發時通過注解，編寫注釋，自動生成API文檔。
2、將前端后臺分開，不會有過分的依賴。
3、界面清晰，無論是editor的實時展示還是ui的展示都十分人性化，如果自己僅僅用markdown來編寫，又要糾結該如何展現，十分痛苦。
下面的兩點我還沒有進行實踐：
1、支持Json和yaml來編寫API文檔，并且支持導出為json、yaml、markdown等格式
2、如果編寫好了API了，可以自動生成相應的SDK，沒錯，可能你的API接口代碼還沒有開始寫，它就能幫你制作相應的SDK了，而且支持幾乎所有主流編程語言的SDK。
SpringBoot,Maven構建SwaggerAPI文檔
第一步：創建SpringBoot Web項目
在這里就不過多進行介紹，只是說一下可能出現的問題：創建好項目之后目錄結構不對，只有src/main/resources文件夾。下圖所示
這時候只需要將JDK版本升級到你安裝的版本就可以，其他文件夾就可以顯現出來：
第二步：創建類以及配置pom.xml
1：配置pom.xml，添加依賴包：
第一個是API獲取的包，第二是官方給出的一個ui界面。三和四是spring boot 需要的jar包。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>2：配置Swagger，創建SwaggerConfig.java類
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構建RESTful APIs")
.description("myapp")
.termsOfServiceUrl("http://blog.csdn.net/java_yes")
.version("1.0").build();
}
}這里有個特別需要注意的地方：
RequestHandlerSelectors.basePackage(“com.swagger”)，這是掃描注解的配置，即你的API接口位置。文章最后我會做總結。
3：創建SpringBoot啟動類
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}4：創建controller
在這里我創建兩個controller，為了解釋@RequestMapping();這兩個Controller沒有任何實際意義，可以隨意創建，我只是為了測試SwaggerAPI
GreetingController
@RestController
@RequestMapping(value = "/test")
public class GreetingController {
private static final String template = "Hello, %s!";
private final AtomicLong counter = new AtomicLong();
@RequestMapping(value = "/swagger")
//@RequestMapping("/swagger")
//@RequestMapping(value = "/swagger",method = RequestMethod.POST)
public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
return new Greeting(counter.incrementAndGet(), String.format(template, name));
}
}BookController
@RestController
@Api(tags = "BookController", description = "BookController | 通過書來測試swagger")
@RequestMapping(value = "/books")
public class BookController {
Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());
@ApiOperation(value="創建圖書", notes="創建圖書")
@ApiImplicitParam(name = "book", value = "圖書詳細實體", required = true, dataType = "Book")
@RequestMapping(value="", method=RequestMethod.POST)
public String postBook(@RequestBody Book book) {
books.put(book.getId(), book);
return "success";
}
@ApiOperation(value = "獲圖書細信息", notes = "根據url的id來獲取詳細信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public Book getBook(@PathVariable Long id) {
return books.get(id);
}
}5：創建SpringBoot 啟動類：
@SpringBootApplication
@ComponentScan(basePackages={"com"})
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}第三步：啟動Swagger
OK，到此為止，整個Swagger我們已經配置完畢。此時訪問http://localhost:8080/swagger-ui.html#/greeting-controller。就可以看到Swagger-UI了。如下圖所示
同樣，根據@RequestMapping()的路徑我們可以進行訪問，再API中進行測試一樣。這里我就進行演示。
坑！！！！我在配置過程中出現的錯誤；
我先發一下我的文件結構：
1：什么都配置了，但是API什么都不顯示。如圖所示：
這個就是我上面說到的問題：RequestHandlerSelectors.basePackage(“com.swagger”)
這個地方配置的是你swagger要加載的接口所在的包名。會去掃秒這個包下的所有Controller。大家看我的文件結構。
如果你配置的是RequestHandlerSelectors.basePackage(“com”)，那么就會掃描所有com包下的Controller，包括com.swagger;以及com.controller。效果就是這樣：
如果你只是單獨配置RequestHandlerSelectors.basePackage(“com.swagger”),或者RequestHandlerSelectors.basePackage(“com.swagger”)。那么就會顯示一個。
2：我配置的是RequestHandlerSelectors.basePackage(“com”)，但API還是只顯示一個，而且不顯示Controller直接訪問地址也報錯，如圖所示：
這個時候可能是SpringBoot的問題了。他并沒有加載到你的另一個controller。
SpringBoot啟動類和Controller類需要在同一包下，controller要在父類包下。
這個時候有兩種解決方案：
1、將未加載的Conrtoller類移動到SpringBoot啟動類所在包。或者將其包名改為啟動類的子包。
2、如上述代碼，在啟動類上加注釋：@ComponentScan(basePackages={“com”})。該注釋會掃描所有com包下的controller并加載。
為什么我GreetingController沒有寫rest方法。但是API中顯示了所有呢？
這個要用@RequestMapping();進行解釋了。
1、@RequestMapping(value = “/swagger”)或者@RequestMapping(“/swagger”)這么寫的時候，就會加載所有method。
2、@RequestMapping(value = “/swagger”,method = RequestMethod.POST)，當你自己設置mathod的時候，就會只創建你設置的method。
看完上述內容，你們掌握怎么在SpringBoot中利用Swagger構建一個api文檔的方法了嗎？如果還想學到更多技能或想了解更多相關內容，歡迎關注億速云行業資訊頻道，感謝各位的閱讀！
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
