如何在spring-boot web項目中啓用swagger

swagger的三個項目及其做用

咱們打開swagger的官網,會發現有三個swagger相關的項目,它們分別是

1. swagger-editor 做用是經過寫代碼,生成文檔描述(一個json文件或其餘格式的api元數據文件)
2. swagger-ui 經過請求文檔描述(一個json文件)的數據,把api的文檔顯示在頁面上
3. swagger-codegenerator 經過文檔描述,來生成實現的代碼

如何在spring-boot項目中集成swagger?

咱們使用springfox-swagger這個項目來把swagger的功能集成到咱們的項目中來,springfox-swagger會自動掃描定義在Controller上的API的相關的註解,生成api的元數據json文件,而後提供的一個swagger的頁面,當咱們訪問這個頁面的時候,前端的js會去請求這個API的元數據文件,把API的相關信息展現出來,方便咱們閱讀和在線調試

集成到spring-boot web項目的步驟:

1.在項目的依賴一遍加入springfox-swagger的相關的依賴

因爲我用的構建工具是gradle,因此就用下邊的方式來引入依賴,

compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

2.定義swagger的配置類,引入啓用swaggger

在spring-boot項目能夠自動掃描到的包下邊,配置如下的配置類:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * Created with Intellij IDEA
 *
 * @author: jiaoyiping
 * Mail: jiaoyiping@gmail.com
 * Date: 2018/11/22
 * Time: 15:38
 * To change this template use File | Settings | Editor | File and Code Templates
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }


    private ApiInfo apiInfo() {
        Contact contact = new Contact("焦一平", "http://www.cnblogs.com/jiaoyiping/", "jiaoyiping@gmail.com");
        return new ApiInfoBuilder()
                .title("元數據管理API接口")
                .description("工具鏈元數據管理")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

3.在Controller裏邊定義API的相關的註解

如下是一個API註解的例子:

@RequestMapping(value = "/checkprojectcode/{projectcode}", method = RequestMethod.GET)
    @ApiOperation(value = "檢查項目編號是否已經存在")
    public ResponseEntity<String> checkProjectCodeExists(@PathVariable("projectcode") String projectCode) {
        ResponseEntity<String> result;
        if (projectService.isProjectCodeExist(projectCode)) {
            result = ResponseEntity.ok("項目編號已存在");
        } else {
            result = ResponseEntity.ok("項目編號不存在");
        }
        return result;
    }

@ApiOperation註解提供了api的名稱和描述信息

最終效果

啓動項目,訪問項目路徑下的 v2/api-docs 這個地址,能夠看到生成的json數據

訪問項目路徑下的 swagger-ui.html路徑,能夠查看和調試咱們寫的api的信息,因此的被@Controller註解的類都會顯示在和這個頁面上,添加了額外的api主機的接口,會有額外的描述信息