精通Spring Boot——第九篇：整合Swagger在線文檔

開發中最煩的一件事是什麼？當你全心全意思考的時候，前端笑眯眯的過來了：「大哥，你沒告訴我該傳什麼參數！」......而後一堆吧啦吧啦扯淡，好了，前端大佬心滿意足的走了，你覺得事情也就這麼結束了。滴滴滴，微信消息來了：「接口怎麼不通啊，你是否是代碼寫的有問題啊？」一頓操做後，登上控制檯，日誌一看。啊~（咱們一塊兒學土撥鼠叫）心裏是崩潰的... 參數少了，參數類型不對，格式不對，各類。這時候很想丟個文檔給前端：你本身看吧！然而，寫文檔真的太麻煩了，懶...只好去逛逛論壇，百度谷歌下有沒有什麼生成在線文檔的工具了，結果如你所願，還真有。今兒個，我們就來走一波spring boot 整合 swagger 生成在線文檔。（呼~~爽，感受用了這個，就能夠不用被前端大佬「騷擾」了）。介紹兩種集成swagger的方式，越用越爽。寫文檔的時候能夠用來和基友尬聊了（編程五分鐘，扯淡兩小時，一天就這麼沒了...） ##第一招 Without Starter 新建項目,pom 文件加上兩個swagger必要的依賴。

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

Swagger的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * swagger經過註解代表該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。
     *
     * @return
     * @Api：修飾整個類，描述Controller的做用
     * @ApiOperation：描述一個類的一個方法，或者說一個接口
     * @ApiParam：單個參數描述
     * @ApiModel：用對象來接收參數
     * @ApiProperty：用對象接收參數時，描述對象的一個字段
     * @ApiResponse：HTTP響應其中1個描述
     * @ApiResponses：HTTP響應總體描述
     * @ApiIgnore：使用該註解忽略這個API
     * @ApiError：發生錯誤返回的信息
     * @ApiImplicitParam：一個請求參數
     * @ApiImplicitParams：多個請求參數
     */
    @Bean
    public Docket createRestApi() {

        /**添加head參數start*/
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("authorization").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        //添加head參數end
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("com.developlee.HangZhou.ZheJiang")
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //有該註解的生成doc
                .apis(RequestHandlerSelectors.basePackage("com.developlee.swagger"))   // 自行修改成本身的包路徑
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars) //set Header
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("DevelopLee的Swagger在線文檔")
                .description("嗯哼嗯哼額~~~swagger文檔很強！")
                .termsOfServiceUrl("http://github.com/developlee")
                .version("1.0")
                .build();
    }
}

寫個Controller類測試

@RestController
public class UserController {

    @GetMapping("/userInfo")
    @ApiOperation(notes = "獲取用戶信息", value = "get user info")
    public String getUserInfo(){
        return "getUserInfo";
    }

    @PostMapping("/addUser")
    @ApiOperation(notes = "添加用戶信息", value = "add user info")
    @ApiImplicitParam(value = "添加用戶", name = "add user", dataType = "java.lang.String", required = true)
    public String addUser(String str){
        return "addUser";
    }
}

啓動項目...訪問 localhost:8080/swagger-ui.html（我滴個龜龜，這就行了？）感動到哭，前端大佬們， see you la la~~（事實上我去找他們聊天了，感覺下這個文檔帶給後端開發人員的福利，尤爲是惰性開發人員，好比在座的全部人)

第二招 With swagger-spring-boot-starter

這裏介紹一個至關牛逼的工具，來自spring4all.com社區開源的swagger-spring-boot-starter。接下來咱們就用這個依賴包開發swagger 文檔。 pom.xml依賴

<dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.1.RELEASE</version>
  </dependency>

@EnableSwagger2Doc開啓文檔

@SpringBootApplication
@EnableSwagger2Doc
public class SwaggerStarterApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerStarterApplication.class, args);
    }
}

###配置示例：

swagger.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.7.1.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=developlee
swagger.contact.url=http://github.com/developlee
swagger.contact.email=developlee@163.com
swagger.base-package=com.developlee
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

swagger.globalOperationParameters[0].name=name one
swagger.globalOperationParameters[0].description=some description one
swagger.globalOperationParameters[0].modelRef=string
swagger.globalOperationParameters[0].parameterType=header
swagger.globalOperationParameters[0].required=true
swagger.globalOperationParameters[1].name=name two
swagger.globalOperationParameters[1].description=some description two
swagger.globalOperationParameters[1].modelRef=string
swagger.globalOperationParameters[1].parameterType=body
swagger.globalOperationParameters[1].required=false

// 取消使用默認預約義的響應消息,並使用自定義響應消息
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

###配置說明--默認配置

- swagger.enabled=是否啓用swagger，默認：true
- swagger.title=標題
- swagger.description=描述
- swagger.version=版本
- swagger.license=許可證
- swagger.licenseUrl=許可證URL
- swagger.termsOfServiceUrl=服務條款URL
- swagger.contact.name=維護人
- swagger.contact.url=維護人URL
- swagger.contact.email=維護人email
- swagger.base-package=swagger掃描的基礎包，默認：全掃描
- swagger.base-path=須要處理的基礎URL規則，默認：/**
- swagger.exclude-path=須要排除的URL規則，默認：空
- swagger.host=文檔的host信息，默認：空
- swagger.globalOperationParameters[0].name=參數名
- swagger.globalOperationParameters[0].description=描述信息
- swagger.globalOperationParameters[0].modelRef=指定參數類型
- swagger.globalOperationParameters[0].parameterType=指定參數存放位置,可選header,query,path,body.form
- swagger.globalOperationParameters[0].required=指定參數是否必傳，true,false

###Path設置

management.context-path=/ops

swagger.base-path=/**
swagger.exclude-path=/ops/**, /error

上面的設置將解析全部除了/ops/開始以及spring boot自帶/error請求路徑。

其中，exclude-path能夠配合management.context-path=/ops設置的spring boot actuator的context-path來排除全部監控端點。 ###分組配置

- swagger.docket.<name>.title=標題
- swagger.docket.<name>.description=描述
- swagger.docket.<name>.version=版本
- swagger.docket.<name>.license=許可證
- swagger.docket.<name>.licenseUrl=許可證URL
- swagger.docket.<name>.termsOfServiceUrl=服務條款URL
- swagger.docket.<name>.contact.name=維護人
- swagger.docket.<name>.contact.url=維護人URL
- swagger.docket.<name>.contact.email=維護人email
- swagger.docket.<name>.base-package=swagger掃描的基礎包，默認：全掃描
- swagger.docket.<name>.base-path=須要處理的基礎URL規則，默認：/**
- swagger.docket.<name>.exclude-path=須要排除的URL規則，默認：空
- swagger.docket.<name>.name=參數名
- swagger.docket.<name>.modelRef=指定參數類型
- swagger.docket.<name>.parameterType=指定參數存放位置,可選header,query,path,body.form
- swagger.docket.<name>.required=true=指定參數是否必傳，true,false
- swagger.docket.<name>.globalOperationParameters[0].name=參數名
- swagger.docket.<name>.globalOperationParameters[0].description=描述信息
- swagger.docket.<name>.globalOperationParameters[0].modelRef=指定參數存放位置,可選header,query,path,body.form
- swagger.docket.<name>.globalOperationParameters[0].parameterType=指定參數是否必傳，true,false

更多移步至 github.com。

最後，以上示例代碼可在個人github.com-swagger-starter以及github.com-swagger及中找到。 個人我的公衆號：developlee的瀟灑人生。 關注了也不必定更新，更新就不得了了。