Spring Cloud Alibaba-Swagger（七）

時間 2019-11-07

標籤 spring cloud alibaba swagger 欄目 Spring 简体版

原文原文鏈接

簡介

swagger能夠方便的幫助咱們構建API文檔。官方網站html

效果

項目整合swagger後默認提供兩種整合方式java

json(http://localhost:8080/v2/api-docs)

html(http://localhost:8080/swagger-ui.html)

我的認爲以上兩種方式產生的API文檔都不夠完美，因此整合插件生成html,放在nginx以供查閱。

步驟以下

運行springboot確保http://localhost:8080/v2/api-docs能夠訪問
生成ASCIIDOC

生成html

整合swagger

加依賴(給出整個pom)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.9.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.virgo</groupId>
    <artifactId>swagger-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger-demo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
        <!--swagger-->
        <swagger2markup.version>1.3.1</swagger2markup.version>
        <swagger.springfox.version>2.9.2</swagger.springfox.version>
        <swagger.model.version>1.5.21</swagger.model.version>
        <asciidoctor.version>1.5.6</asciidoctor.version>
        <generated.source.directory>src/docs/asciidoc/generated</generated.source.directory>
        <generated.output.directory>src/docs/asciidoc/generated/all</generated.output.directory>
        <asciidoctor.html.output.directory>src/docs/asciidoc/html</asciidoctor.html.output.directory>
    </properties>

    <!--swagger-->
    <pluginRepositories>
        <pluginRepository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </pluginRepository>
        <pluginRepository>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

    <repositories>
        <repository>
            <id>jcentral</id>
            <name>bintray</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.springfox.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger.model.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>${swagger.model.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <!--swagger-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>${swagger2markup.version}</version>
                <configuration>
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                    <!-- 生成爲單個文檔，輸出路徑 -->
                    <outputFile>${generated.output.directory}</outputFile>
                    <config>
                        <!-- ascii格式文檔 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor.version}</version>
                <configuration>
                    <!-- asciidoc文檔輸入路徑 -->
                    <sourceDirectory>${generated.source.directory}</sourceDirectory>
                    <!-- html文檔輸出路徑 -->
                    <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <!-- html文檔格式參數 -->
                    <attributes>
                        <doctype>book</doctype>
                        <!--菜單欄在左邊-->
                        <toc>left</toc>
                        <!--多標題排列-->
                        <toclevels>3</toclevels>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

複製代碼

寫註解

無
複製代碼

寫配置

package com.virgo.swaggerdemo.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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 zhaozha
 * @date 2019/10/12 上午10:05
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用戶中心Restful APIs")
                .description("用戶中心API接口文檔")
                .termsOfServiceUrl("")
                .version("1.0.0")
                .contact(new Contact("zhao", "", "")).build();
    }

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.virgo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(this.apiInfo()).enable(true);

        //.globalOperationParameters(parameters);
    }
}

複製代碼

常見註解

對象	註解	屬性	說明
對象	@ApiModel		描述對象總體
		value	描述對象總體
		description	描述對象總體
對象屬性	@ApiModelProperty		描述對象屬性
		value	描述對象屬性
類	@Api		描述類總體
		value	url的路徑
		tags	覆蓋value
		description	描述
		basePath	基本路徑
		position	配置多個Api 想改變顯示的順序位置
		produces	格式如application/json
		consumes	同produces
		protocols	協議如http
		authorizations	認證
		hidden	是否隱藏
方法	@ApiOperation		描述方法總體
		value	url的路徑
		tags	覆蓋value
		description	描述
		basePath	基本路徑
		position	配置多個Api 想改變顯示的順序位置
		produces	格式如application/json
		consumes	同produces
		protocols	協議如http
		authorizations	認證
		hidden	是否隱藏
		response	返回的對象
		responseContainer	返回的集合如List/Map...
		httpMethod	GET/POST...
		code	狀態碼
		extensions	拓展
方法響應	@ApiResponse		響應
		code	http狀態碼
		message	描述
		response	響應類
		reference	參考
		responseHeaders	頭
		responseContainer
方法響應頭	@ResponseHeader		響應頭
		name	響應頭名稱
		description	描述
		response	響應類
		responseContainer
響應集	@ApiResponses		響應集
單個響應	@ApiResponse		響應集中單個響應
		code	http狀態碼
		message	描述
方法屬性	@ApiParam		描述方法屬性
		name	屬性名稱
		value	屬性值
		defaultValue	默認屬性值
		allowableValues	能夠不配置
		required	是否必填
		access
		allowMultiple
		hidden	是否隱藏
		example	舉例
屬性集	@ApiImplicitParams		屬性集
單個屬性	@ApiImplicitParam		屬性集中單個屬性
		paramType
		name	含義
		value	名稱
		dataType	類型
		required	是否必填
		defaultValue	默認值