您好,登錄后才能下訂單哦!
前言
swagger,中文“拽”的意思。它是一個(gè)功能強(qiáng)大的api框架,它的集成非常簡(jiǎn)單,不僅提供了在線(xiàn)文檔的查閱,
而且還提供了在線(xiàn)文檔的測(cè)試。另外swagger很容易構(gòu)建restful風(fēng)格的api。
Swagger是一組圍繞OpenAPI規(guī)范構(gòu)建的開(kāi)源工具,可幫助設(shè)計(jì)、構(gòu)建、記錄和使用REST API。
簡(jiǎn)單說(shuō)下,它的出現(xiàn)就是為了方便進(jìn)行測(cè)試后臺(tái)的restful形式的接口,實(shí)現(xiàn)動(dòng)態(tài)的更新,當(dāng)我們?cè)诤笈_(tái)的接口
修改了后,swagger可以實(shí)現(xiàn)自動(dòng)的更新,而不需要認(rèn)為的維護(hù)這個(gè)接口進(jìn)行測(cè)試。
swagger通過(guò)注解表明該接口會(huì)生成文檔,包括接口名、請(qǐng)求方法、參數(shù)、返回信息的等等。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
通過(guò)@Configuration注解,表明它是一個(gè)配置類(lèi),@EnableSwagger2開(kāi)啟swagger2。
apiINfo()配置一些基本的信息。apis()指定掃描的包會(huì)生成文檔。
再通過(guò)createRestApi函數(shù)創(chuàng)建Docket的Bean之后,apiInfo()用來(lái)創(chuàng)建該Api的基本信息(這些基本信息會(huì)
展現(xiàn)在文檔頁(yè)面中)。select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例用來(lái)控制哪些接口暴露給Swagger來(lái)
展現(xiàn),本例采用指定掃描的包路徑來(lái)定義,Swagger會(huì)掃描該包下所有Controller定義的API,并產(chǎn)生文檔內(nèi)容
(除了被@ApiIgnore指定的請(qǐng)求)。
package com.lance.learn.springbootswagger.configuration; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @author lance(ZYH) * @function Swagger啟動(dòng)配置類(lèi) * @date 2018-07-09 21:24 */ @Configuration @EnableSwagger2 public class SwaggerConfiguration { /** * swagger2的配置文件,這里可以配置swagger2的一些基本的內(nèi)容,比如掃描的包等等 * @return */ @Bean public Docket createRestfulApi(){ return new Docket(DocumentationType.SWAGGER_2) .pathMapping("/") .select() .apis(RequestHandlerSelectors.basePackage("com.lance.learn.springbootswagger.controller")) //暴露接口地址的包路徑 .paths(PathSelectors.any()) .build(); } /** * 構(gòu)建 api文檔的詳細(xì)信息函數(shù),注意這里的注解引用的是哪個(gè) * @return */ private ApiInfo apiInfo(){ return new ApiInfoBuilder() //頁(yè)面標(biāo)題 .title("Spring Boot 測(cè)試使用 Swagger2 構(gòu)建RESTful API") //創(chuàng)建人 .contact(new Contact("LanveToBigData", "http://www.cnblogs.com/zhangyinhua/", "917484312@qq.com")) //版本號(hào) .version("1.0") //描述 .description("API 描述") .build(); } }
描述主要來(lái)源于函數(shù)等命名產(chǎn)生,對(duì)用戶(hù)并不友好,我們通常需要自己增加一些說(shuō)明來(lái)豐富文檔內(nèi)容。
如下所示,我們通過(guò)@ApiOperation注解來(lái)給API增加說(shuō)明、通過(guò)@ApiImplicitParams、@ApiImplicitParam
注解來(lái)給參數(shù)增加說(shuō)明。
1)實(shí)例一
package com.lance.learn.springbootswagger.controller; import com.lance.learn.springbootswagger.bean.Book; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import springfox.documentation.annotations.ApiIgnore; import java.util.*; /** * @author lance(ZYH) * @function * @date 2018-07-09 21:39 */ @RestController @RequestMapping(value = "/bookcurd") public class BookController { Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>()); @ApiOperation(value="獲取圖書(shū)列表", notes="獲取圖書(shū)列表") @RequestMapping(value={""}, method= RequestMethod.GET) public List<Book> getBook() { List<Book> book = new ArrayList<>(books.values()); return book; } @ApiOperation(value="創(chuàng)建圖書(shū)", notes="創(chuàng)建圖書(shū)") @ApiImplicitParam(name = "book", value = "圖書(shū)詳細(xì)實(shí)體", required = true, dataType = "Book") @RequestMapping(value="", method=RequestMethod.POST) public String postBook(@RequestBody Book book) { books.put(book.getId(), book); return "success"; } @ApiOperation(value="獲圖書(shū)細(xì)信息", notes="根據(jù)url的id來(lái)獲取詳細(xì)信息") @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); } @ApiOperation(value="更新信息", notes="根據(jù)url的id來(lái)指定更新圖書(shū)信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "圖書(shū)ID", required = true, dataType = "Long",paramType = "path"), @ApiImplicitParam(name = "book", value = "圖書(shū)實(shí)體book", required = true, dataType = "Book") }) @RequestMapping(value="/{id}", method= RequestMethod.PUT) public String putUser(@PathVariable Long id, @RequestBody Book book) { Book book1 = books.get(id); book1.setName(book.getName()); book1.setPrice(book.getPrice()); books.put(id, book1); return "success"; } @ApiOperation(value="刪除圖書(shū)", notes="根據(jù)url的id來(lái)指定刪除圖書(shū)") @ApiImplicitParam(name = "id", value = "圖書(shū)ID", required = true, dataType = "Long",paramType = "path") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { books.remove(id); return "success"; } @ApiIgnore//使用該注解忽略這個(gè)API @RequestMapping(value = "/hi", method = RequestMethod.GET) public String jsonTest() { return " hi you!"; } }
2)實(shí)例二
package com.lance.learn.springbootswagger.controller; import com.lance.learn.springbootswagger.bean.User; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import java.util.*; /** * @author lance(ZYH) * @function * @date 2018-07-09 22:00 */ @RestController @RequestMapping(value="/users") public class UserDetailController { static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>()); @ApiOperation(value="獲取用戶(hù)列表", notes="") @RequestMapping(value={""}, method= RequestMethod.GET) public List<User> getUserList() { List<User> r = new ArrayList<User>(users.values()); return r; } @ApiOperation(value="創(chuàng)建用戶(hù)", notes="根據(jù)User對(duì)象創(chuàng)建用戶(hù)") @ApiImplicitParam(name = "user", value = "用戶(hù)詳細(xì)實(shí)體user", required = true, dataType = "User") @RequestMapping(value="", method=RequestMethod.POST) public String postUser(@RequestBody User user) { users.put(user.getId(), user); return "success"; } @ApiOperation(value="獲取用戶(hù)詳細(xì)信息", notes="根據(jù)url的id來(lái)獲取用戶(hù)詳細(xì)信息") @ApiImplicitParam(name = "id", value = "用戶(hù)ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable Long id) { return users.get(id); } @ApiOperation(value="更新用戶(hù)詳細(xì)信息", notes="根據(jù)url的id來(lái)指定更新對(duì)象,并根據(jù)傳過(guò)來(lái)的user信息來(lái)更新用戶(hù)詳細(xì)信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶(hù)ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用戶(hù)詳細(xì)實(shí)體user", required = true, dataType = "User") }) @RequestMapping(value="/{id}", method=RequestMethod.PUT) public String putUser(@PathVariable Long id, @RequestBody User user) { User u = new User(); users.put(id, u); return "success"; } @ApiOperation(value="刪除用戶(hù)", notes="根據(jù)url的id來(lái)指定刪除對(duì)象") @ApiImplicitParam(name = "id", value = "用戶(hù)ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { users.remove(id); return "success"; } }
https://github.com/LanceToBigData/SpringBootLearning/tree/develop/SpringBoot-Swagger
總結(jié)
以上就是這篇文章的全部?jī)?nèi)容了,希望本文的內(nèi)容對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,如果有疑問(wèn)大家可以留言交流,謝謝大家對(duì)億速云的支持。
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng),如果涉及侵權(quán)請(qǐng)聯(lián)系站長(zhǎng)郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。