自動ドキュメント生成ツール-Swaggerの使用記録

1使用理由

夏の宿題で、先生は私たちに闊歩を使ってAPIのドキュメントを書くことを望んでいます。
APIを文書化する必要があるのはなぜですか？

APIを発見し、使用方法を学び、最終的に統合する際の開発者の総合的なエクスペリエンスは、開発者エクスペリエンスと呼ばれます。APIドキュメントは、優れた開発者エクスペリエンスの鍵です。

2Swagger構成

使用するには、このリンクのコンテンツを参照してください：swaggerとSpringBootプロジェクトの統合

最初にMavenの依存関係を紹介します

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>

次に、SpringBootのスタートアップクラスでSwaggerを有効にします

@EnableSwagger2
@SpringBootApplication
public class WeiboserviceApplication {
    
    

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

}

より良い方法は、個別の構成クラスを構築することです。
ここでは、公開された（公開された）APIのアドレスを指定し、パッケージ名を設定します。

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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    

    @Bean
    public Docket createRestApi() {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo指定测试文档基本信息，这部分将在页面展示
                .apiInfo(apiInfo())
                .select()
                //apis() 控制哪些接口暴露给swagger，
                // RequestHandlerSelectors.any() 所有都暴露，会多出一个默认的error-service-controller
                // RequestHandlerSelectors.basePackage("com.info.*")  指定包位置
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    //文档的总体信息
    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("测试项目标题")
                .description("接口描述")
                //联系人实体类
                .contact(
                        new Contact("名字", "网址", "邮箱")
                )
                //版本号
                .version("1.0.0-SNAPSHOT")
                .build();
    }
}

2番目の方法に従ってSwaggerを導入すると、構成が完了します。Postmanを使用してhttp：// localhost：8080 / v2 / api-docsにリクエストを送信し、テストでき

ます。明らかに、返される結果はドキュメントではありません。欲しい。、Swagger-uiが登場する時が来た

3 Swagger UI使用

Swagger UIgithubホームページ

Swagger UIは、依存関係のないHTML、JavaScript、およびCSSアセットのコレクションであり、Swagger準拠のAPIから美しいドキュメントとサンドボックスを動的に生成します。Swagger UIには依存関係がないため、任意のサーバー環境またはローカルマシンでホストできます。

この記事では、最新の3.xバージョンではなく2.xバージョンを使用します。これは、2.0の使用シナリオがより簡潔であり、標準化された大規模プロジェクトには3.0が適しているためです。

インターフェースの説明は、Swagger仕様（JSONファイル）を介してSwagger 3.0で記述され、Swagger 2.0は、インターフェースに一連の注釈を提供することによって記述されます。

最初にMavenの依存関係を紹介します

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

導入後、ブラウザhttp：// localhost：8080 / swagger-ui.html＃/のベースURLとしてlocalhost：8080を使用してswagger UIページに直接アクセスできます。
コントローラにコメントを追加せずに、デフォルトのドキュメントコントローラクラスに注釈を付けます。一般的な注釈は次のとおり

です。

@Api（value = ""、tag = ""）：クラスの役割を説明するためにクラスで使用されます。

@ApiOperation：メソッドの説明をAPIに追加するためのアノテーション。
ここでhttpMethodを指定する必要があることに注意してください。そうしないと、メソッドごとにドキュメントがあります
@ApiImplicitParams：メソッドに一連のパラメーターの説明を含めるために使用されます。

@ApiImplicitParam：メソッドパラメーターに命令を追加するために注釈を付けるために使用されます。

@ApiResponses：一連の応答を表すために使用されます

@ApiResponse：@ApiResponsesで使用され、通常、誤った応答メッセージを表現するために使用されます

コード：400などの番号

メッセージ：「リクエストパラメータが入力されていません」などの情報

応答：例外をスローしたクラス

   @ApiResponses({
        @ApiResponse(code = 1000, message = "非HTTP状态码，返回值JSON code字段值，描述：成功"),
        @ApiResponse(code = 401, message = "非HTTP状态码，返回值JSON code字段值，描述：无token")
})

@ApiModel：モデルの情報を記述します（通常、@ ApiImplicitParamアノテーションを使用して要求パラメーターを記述できない場合に使用されます）

@ApiModelProperty：モデルのプロパティを説明します

@CrossOrigin(origins = "*")
@RestController
@Api(value = "UserServiceControl23ler")
public class UserServiceController {
    
    


    @Autowired
    private UserService userService;

     @ApiOperation(notes = "get user info by userID", value = "get user info",httpMethod = "GET")
    @RequestMapping(path="/user/getUser")
    public User getUser(@ApiParam(name = "userId", value = "The user ID of a WeiBo user,should be a Long Integer") @RequestParam("userId") Long uid){
    
    
        System.out.println("*****getWeibo*****");
        return userService.findAllById(uid);
    }
}

注釈を追加した後のドキュメント効果。小規模なプロジェクトの場合、これらの注釈で十分です

注意が必要な4つの事項

Swaggerは、表示されるドキュメント情報を取得するために、注釈に基づいてインターフェイスにリクエストを送信する必要があります。この時点で、渡されたパラメータはすべて空です。バックエンドが例外を処理しない場合、次のようなエラーが報告されます。

java.lang.NumberFormatException: For input string: ""

投稿方法の説明は当面簡単な解決策はありませんが、独自の方法を書いたブログがたくさんありますので、検索してみてください。私の計画は次のとおりです。

    @ApiOperation(notes = "deleteById", value = "delete one user", httpMethod = "POST")
    @ApiImplicitParams({
    
    
            @ApiImplicitParam(name = "nickname", value = "the nickname of the iLife user"),
            @ApiImplicitParam(name = "account", value = "the account of the iLife user"),
            @ApiImplicitParam(name = "password", value = "the password of the iLife user"),
            @ApiImplicitParam(name = "email", value = "the email of the iLife user")
    }
    )
    @RequestMapping(path = "/auth/logUp")
    public ResponseEntity<?> logUp(@ApiIgnore @RequestBody Map<String, String> params) {
    
    
        String nickname = params.get("nickname");
        String account = params.get("account");
        String password = params.get("password");
        String email = params.get("email");
        System.out.println("********** deleteById **********");
        return userService.save(nickname, account, password, email);
    }

paramを使用してヘッダーのデータで渡されるパラメーターを表し、requestBodyパラメーターを無視します（そうでない場合は余分なブラックボックスがあります）。操作の効果は次のとおりです。