springmvc 整合 swagger 自動生成 web api 文檔

前提條件: 已引入spring以及spring mvc的包,并做好了相關配置，能夠正常運行

一. pom中引入swagger相關的依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-aop</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-beans</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.9</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-staticdocs</artifactId>
    <version>2.5.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml.jackson.dataformat</groupId>
            <artifactId>jackson-dataformat-yaml</artifactId>
        </exclusion>
        <exclusion>
            <groupId>joda-time</groupId>
            <artifactId>joda-time</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-joda</artifactId>
        </exclusion>
    </exclusions>
</dependency>

二. web.xml中啟用web容器的default servlet，將靜態(tài)資源交由web容器處理(這里主要指html文件)

<!-- 讓容器來處理靜態(tài)文件,防止spring mvc去處理(spring mvc處理靜態(tài)文件的能力不如容器本身) -->
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.js</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.css</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.jpg</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.png</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.gif</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.html</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>*.wof</url-pattern>
</servlet-mapping>

四. 創(chuàng)建ApplicationSwaggerConfig類

package apidoc;

import org.springframework.context.annotation.Bean;

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 pan
 *
 */
@EnableSwagger2
public class ApplicationSwaggerConfig {

    @Bean
    public Docket addUserDocket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        Contact contact = new Contact("潘志勇", "", "zhiyong.pan@comix.com.cn");
        ApiInfo apiInfo = new ApiInfo("進銷存管理系統(tǒng)", "WEB API文檔", "V0.0.1", "", contact, "", "");
        docket.apiInfo(apiInfo);
        return docket;
    }
}

三.spring mvc配置文件中加入如下配置

<!-- Include a swagger configuration -->
    <bean name="applicationSwaggerConfig" class="apidoc.ApplicationSwaggerConfig" />
    <mvc:default-servlet-handler/>

四. API編寫測試

package com.qc.invoicing.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
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.ResponseBody;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@Controller
@RequestMapping(value = "/test", produces = { "application/json;charset=utf-8" })
@Api(value = "/test", description = "測試Contrler")
public class TestController {

    @RequestMapping(value = "/restStyle/{id}", method = RequestMethod.GET)
    @ApiOperation(notes = "/restStyle", httpMethod = "GET", value = "rest風格方法")
    @ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
    @ResponseBody
    public StringAPIResponse restStyle(@ApiParam(required = true, value = "主鍵") @PathVariable(value = "id") long id) {
        System.err.println(id);
        StringAPIResponse apiResponse = new StringAPIResponse();
        apiResponse.setMsg("操作成功");
        apiResponse.setData("你好");
        return apiResponse;
    }

    @RequestMapping(value = "/getStyle", method = RequestMethod.GET)
    @ApiOperation(notes = "/getStyle", httpMethod = "GET", value = "get風格方法")
    @ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
    @ResponseBody
    public StringAPIResponse getStyle(@ApiParam(required = true, value = "主鍵") @RequestParam("id") long id) {
        System.err.println(id);
        StringAPIResponse apiResponse = new StringAPIResponse();
        apiResponse.setMsg("操作成功");
        apiResponse.setData("你好");
        return apiResponse;
    }

    @RequestMapping(value = "/postStyle", method = RequestMethod.POST)
    @ApiOperation(notes = "/postStyle", httpMethod = "POST", value = "post風格方法")
    @ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
    @ResponseBody
    public StringAPIResponse postStyle(@ApiParam(required = true, value = "簡單數據") @RequestBody SimpleData data) {
        System.err.println(data.getName());
        StringAPIResponse apiResponse = new StringAPIResponse();
        apiResponse.setMsg("操作成功");
        apiResponse.setData("你好");
        return apiResponse;
    }

    @RequestMapping(value = "/traditionStyle", method = RequestMethod.GET, produces = { "application/xml;charset=utf-8" })
    @ApiOperation(notes = "轉入頁面:/WEB-INF/jsp/test.jsp", httpMethod = "GET", value = "傳統(tǒng)風格方法")
    @ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
    public String traditionStyle() {
        return "/test";
    }

}

class SimpleData {

    @ApiModelProperty(value = "主鍵", hidden = false)
    private long id;

    @ApiModelProperty(value = "名稱", required = true)
    private String name;

    @ApiModelProperty(value = "年齡")
    private int age;

    public long getId() {
        return id;
    }

    public void setId(long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

}

abstract class APIResponse<T> {

    @ApiModelProperty(value = "操作是否成功")
    private boolean optSuc = true;

    @ApiModelProperty(value = "操作失敗時的提示信息")
    private String msg;

    @ApiModelProperty(value = "返回結果")
    private T data;

    public boolean isOptSuc() {
        return optSuc;
    }

    public void setOptSuc(boolean optSuc) {
        this.optSuc = optSuc;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

class StringAPIResponse extends APIResponse<String> {

}

五. 啟動jetty(如果是使用maven命令運行web項目，請使用jetty作為web容器，否則無法訪問swagger)

mvn jetty:run

//訪問地址:
http://ip:端口/項目名/swagger-ui.html#/
例如：
http://localhost:9080/test-project/swagger-ui.html

結果：

Paste_Image.png
最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
【社區(qū)內容提示】社區(qū)部分內容疑似由AI輔助生成，瀏覽時請結合常識與多方信息審慎甄別。
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發(fā)布，文章內容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務。

相關閱讀更多精彩內容

  • Spring Boot 參考指南 介紹 轉載自:https://www.gitbook.com/book/qbgb...
    毛宇鵬閱讀 47,279評論 6贊 342
  • Spring Cloud為開發(fā)人員提供了快速構建分布式系統(tǒng)中一些常見模式的工具（例如配置管理，服務發(fā)現，斷路器，智...
    卡卡羅2017閱讀 136,645評論 19贊 139
  • spring官方文檔：http://docs.spring.io/spring/docs/current/spri...
    牛馬風情閱讀 1,856評論 0贊 3
  • 從三月份找實習到現在，面了一些公司，掛了不少，但最終還是拿到小米、百度、阿里、京東、新浪、CVTE、樂視家的研發(fā)崗...
    時芥藍閱讀 42,818評論 11贊 349
  • 一生中 我們要經歷許多事情 要相識相交許多人 而心靈像一個篩子 在世事顛沛流離中 慢慢的一些人就漏掉了 不過對于智...
    一米陽光HUIWEI閱讀 488評論 0贊 51

友情鏈接更多精彩內容